Authentication & identity

Authentication answers two separate questions:

1. Which application or key is calling Introspection?
2. Which end user is the application running work for?

Keeping those questions separate is essential in a multi-user application. The caller credential fixes the Introspection organization, Introspection project, environment, and capabilities. The end-user identity scopes that user’s tasks, conversations, files, and memory inside that Introspection project.

Choose an authentication method

All three ultimately produce a bearer token scoped to an Introspection project and linked to an agent member. They differ in how the caller authenticates and whether Introspection independently verifies the end-user identity. The agent member identifies the application-side agent; the end-user identity identifies the person whose task and conversation are being created.

API key

An API key is a long-lived secret issued for one Introspection project and environment. A trusted server sends it as Authorization: Bearer <token> when it uses the SDK or REST API.

The key authenticates the backend as its linked agent member, not as an end user. The backend may attach an end-user identity when it opens a runner:

const runner = await client.runtimes("support-agent").run({
  identity: { user_id: applicationUser.id },
});

That user ID is caller-attributed: Introspection trusts the authenticated backend to supply the correct subject. Use an API key when the application server is inside your trust boundary and a static credential is acceptable.

API keys never belong in a browser, mobile binary, agent sandbox, or other environment where an end user can read them.

Service-account application

A service account is a confidential application principal with a client ID, client secret, and linked agent member. Its backend exchanges those credentials through OAuth client_credentials for a short-lived access token scoped to an Introspection project and that agent.

Like an API key, a service account opens a runner with identity.user_id, identity.anonymous_id, or identity.conversation_id. That identity is caller-attributed: the service account authenticates the application, and the application vouches for the subject it passes.

This is a B2B2C flow. The browser authenticates with your application, your trusted backend supplies that user’s identity when it opens the Introspection runner, and the browser receives only the resulting short-lived, identity-bound session.

Use a service account when you want:

• short-lived access tokens instead of a long-lived API key;
• a distinct application principal with capped scopes;
• a B2B2C backend token broker where your server already authenticates users;
• one runtime serving many application users while keeping their work separate.

The service-account secret stays on the backend. A browser broker returns only the identity-bound runner token, resolved runtime ID, and Data Plane URL; the browser exchanges that token for an HttpOnly Data Plane session.

Federated application

A federated application links Introspection to an identity provider you operate, such as Auth0, Supabase Auth, or another OIDC/JWKS issuer. The backend exchanges the end user’s signed IdP token through RFC 8693 token exchange.

Introspection verifies the configured issuer, audience, signature, and required claims before minting an Introspection-project-scoped token for a customer member. The customer owns the work, while the application’s linked agent member identifies the agent acting for them. The resulting customer identity is federation-proven: it came from the partner IdP rather than a user ID asserted by application code.

Federation serves the same B2B2C and browser-client architecture as a service account. Choose it when Introspection should verify the end user’s IdP token instead of trusting your backend to send the correct identity—for example, when an agent calls your MCP server and the server requires an independently proven subject.

Attribution and assertion are different trust levels

When Introspection calls an authorized partner endpoint, it can carry the task identity in a short-lived, platform-signed JWT. The JWT type tells the receiver how that identity was established:

An endpoint must choose which types it accepts. A valid signature proves that Introspection issued the JWT; the type claim says whether the underlying user was caller-attributed or federation-proven.

Identity scopes user-owned work

Within an Introspection project, the stable end-user identity scopes durable personal resources:

• tasks and runs;
• conversations;
• files;
• memory.

One runtime can therefore serve many end users without mixing their state. Authentication establishes the caller for the Introspection project; identity establishes the user boundary inside that project.

That boundary is per-user by default; to let a group of users share tasks and files, give them a common tag, which an identity assertion can seed through identity.tags — see Tags.

Related

• SDK authentication: configure API keys, service accounts, token exchange, and browser brokers.
• Organizations & projects: the Introspection tenant and project that credentials resolve to.
• MCP and federation: forward a task identity to an external MCP server.
• Tags: share tasks and files across a cohort instead of one member at a time.
• Connectors: connect an end customer’s own provider account to an agent.
• Security & data: credential handling and isolation guarantees.