Identity and Workspaces
How deployments, namespaces, tenants, identities, workspaces, and connections fit together.
When MarcoPolo receives a call, its credential determines the caller's identity. That identity determines the workspace, visible connections, permissions, and audit attribution. The layers below describe where the identity lives.
| Term | Meaning |
|---|---|
| Deployment | An installed MarcoPolo service, such as the hosted service at mcp.marcopolo.dev or a BYOC installation on AWS, Google Cloud, Azure, VMware, or OpenShift. |
| MarcoPolo namespace | A logical product boundary within a deployment. The hosted service's native namespace is marcopolo; application platforms can be provisioned with a dedicated namespace. A MarcoPolo namespace is distinct from a Kubernetes namespace. |
| Tenant | An organization scope within a namespace, derived from a user's work email domain. Users in one tenant can share connections according to its policies; users in another tenant cannot. |
| Identity | A person, service account, or user represented by a short-lived namespace token. The credential on each call selects one identity. |
| Workspace | The identity's persistent files and data workspace. A running session uses it; the workspace remains available across sessions. |
| Connection | A governed route to a database, warehouse, file store, or application. Its owner and sharing grants determine which identities may use it. A connection is not the same thing as a workspace. |
For example, [email protected] and [email protected] are separate identities and have separate workspaces in the same acme.com tenant. A connection owned by Jane appears to the analyst only when it is shared with the analyst or their tenant. A service account also has its own workspace and sees only connections explicitly granted to it.
In a dedicated MarcoPolo namespace, your backend authenticates an end user and requests a short-lived MarcoPolo token for that user's work email. MarcoPolo derives the tenant from the email and provisions the user's workspace as needed. The namespace key stays on your backend and cannot act directly as a user. See MarcoPolo Namespace with Per-User Workspaces.
Which workspace should an application use?
- Personal workspace: Good for an individual using an AI assistant or testing an integration. A personal API token acts as that person.
- Service account workspace: Good for application work that may use one shared set of connection grants. Calls are attributed to the service account; your application must keep its own end-user context where needed.
- Per-user workspace in a MarcoPolo namespace: Good when connections, permissions, workspace files, or audit need to follow each application user. Your backend exchanges a provisioned namespace key for a short-lived token for each user.
For a side-by-side choice of identities and interfaces, see Choose an Integration. For the directory layout and data workflow inside a workspace, see Workspace.