MarcoPolo Namespace with Per-User Workspaces

Use a dedicated MarcoPolo namespace with per-user workspaces when your application must preserve each user's MarcoPolo identity. Your application authenticates the person first. Its backend then exchanges a provisioned namespace key for a short-lived token bearing that user's work email. MarcoPolo uses the token to select or provision their workspace and enforce their connection permissions.

Request a user token

import os
from marcopolo import Marcopolo, MarcopoloNamespace


async def list_user_connections(authenticated_user_email: str):
    async with MarcopoloNamespace(
        api_key=os.environ["MARCOPOLO_NAMESPACE_KEY"]
    ) as namespace:
        token = await namespace.issue_user_token(authenticated_user_email)

    async with Marcopolo(access_token=token.access_token) as client:
        return await client.workspace.connections()

Use only an email your application has authenticated. MarcoPolo derives the tenant from its work email domain; consumer email domains are refused. Users in the same tenant may share connections according to its policies, but their workspaces remain separate.

User tokens expire after five minutes. Request a fresh token through the namespace key when you need another session; do not reuse one user's token for another user. The namespace key can issue user tokens but cannot serve as a data-access bearer token.

The same user token can authenticate calls through the Python SDK, direct REST API, or an MCP client that sends it as a bearer token. Your choice of interface does not change the user identity or its permissions.

Plan the application flow

1. Authenticate the end user in your application and establish their work email.
2. On your backend, request a MarcoPolo user token with the namespace key.
3. Use that user token for the user's MarcoPolo requests. Create field-based connections with the SDK, start hosted OAuth setup for providers that require browser authorization, or use connections already shared with the user.
4. Renew by requesting another user token after expiry. Keep the namespace key and user tokens out of client-side code and prompts.

Namespace and tenant are different boundaries. One dedicated MarcoPolo namespace can contain multiple tenants; within each tenant, users have distinct workspaces. See Identity and workspaces for the hierarchy and Choose an Integration to compare this model with a service account.

To return a user to your application after hosted OAuth setup, ask the MarcoPolo team to register your HTTPS return origin for the namespace, then pass return_url to client.connection_setup.start(). The return's query parameters are hints; confirm the outcome with client.connection_setup.get() using a token for the same user. Google Drive setup does not support an embedded return URL.