Multi-tenancy and authentication: to fastn and from fastn

fastn is multi-tenant, and authentication runs in two directions. Access keys authenticate a caller INTO the gateway (inbound). Connections are the credentials the gateway holds to reach your apps ON your behalf (outbound). This page defines the tenancy hierarchy and both auth directions with one consistent vocabulary, so a scope is never resolved to the wrong level.

The tenancy hierarchy

Every level below the platform is a tenant, nested. Each level has exactly one name:

• Platform - fastn itself, the gateway that hosts everyone.
• Organization - a fastn customer (for example Katana). The platform's direct customer.
• Workspace - a division inside an Organization (for example meetings), written owner:slug, e.g. katana:meetings.
• End-org - a customer that the Organization itself serves (for example HP), named per request with the X-Org-Id header.
• End-user - a person inside an End-org (for example alice@hp.com), named with the X-User-Id header.

An End-org and an End-user are the Organization's own tenants. The word tenant is never a field name - use Organization, Workspace, End-org, and End-user, so nobody scopes a connection to the wrong level.

How a connection is addressed

A connection - one stored credential to one app - is addressed by four parts:

• WHERE - the Workspace the credential lives in (the full id, for example katana:meetings). Never the bare Organization.
• END-ORG - the End-org the credential is for (from X-Org-Id).
• WHO - the identity acting: default (the shared credential) or a specific End-user (from X-User-Id).
• WHICH - the account, when one identity has more than one login for the same app (for example two HubSpot orgs).

Authentication TO fastn: access keys

An access key is how an agent, client, or user authenticates into the gateway. fastn supports several kinds:

• API / agent key - a long-lived bearer token (ucl_...), for machines and agents.
• OAuth client credentials - a client id and client secret, for server-to-server callers.
• OAuth browser login - a user signs in through the portal (dynamic client registration + PKCE) and gets a session token.
• mTLS - a client certificate, for callers that authenticate with mutual TLS.

Authentication FROM fastn: connections to connected apps

A connected app (a connector) is what the gateway calls for you. Connectors come in three kinds: MCP servers, custom HTTP connectors, and workflow tools. A connection is one stored authorization to a connector for a given (Workspace, End-org, identity, account). The connector's identity mode decides which credential a call resolves to:

• Shared (one shared account) - a single credential for the Organization; every call uses it (identity default).
• Per-user (each user) - each End-user connects their own account (identity = X-User-Id).
• Per-org (each org) - each End-org gets its own shared account, resolved from X-Org-Id.

Delegation: one key serving many End-orgs and End-users

A delegated key carries no fixed customer. Each request names the End-org (X-Org-Id) and the End-user (X-User-Id); the gateway resolves the connection within that scope. The End-org is namespaced under the caller, so two callers' HP never share credentials:

POST https://connect.fastn.dev/<workspace>/mcp
Authorization: Bearer ucl_<agent-key>
X-Org-Id: HP
X-User-Id: alice@hp.com

Multiple accounts per connector

A single identity - an End-org's shared credential, or an End-user - can hold more than one account for the same connector, for example two HubSpot orgs. Each account is a full, independent credential. A per-call selector (X-Connection-Id) picks which one to use; otherwise the active account; otherwise the default.