Tokens for OAuth services

An API key belongs to your company. An OAuth connection is stored in a bucket and names one connected person through its grant. When an agent calls a service like Jira, Google, or Slack, the provider needs to know which connected user it is acting for — and Fused calls that identifier the end-user reference. This page covers getting one to the Engine.

Before the token exists

Provider app credentials must be registered before connecting a user. A dynamic MCP token can start with an unconnected user and let a capable client request consent when an operation needs it. A fixed token requires the connection to exist when you issue it. To connect beforehand, follow these steps:

Store the provider app’s client_id and client_secret as one atomic pair in the bucket. The Engine derives the callback as <engine.public_url>/workspace/connect/callback; redirect_uri is not credential input.

fused-cli secret set jira --bucket default

Choose the OAuth method when prompted. For automation, use the explicit --no-input --value-stdin form.

Connect a user

One person’s grant against that registration. The --user-ref you choose here is the value everything downstream uses.

fused-cli workspace service connect jira \
  --bucket default \
  --user-ref user_123 \
  --scope read:jira-work

Keep --user-ref stable and meaningful — it is your identifier for that person, not the provider’s. The app credentials and connected-user tokens have separate lifecycles. A compatible target service can reuse a source app through ref: "${bucket.auth.<source-service>.<source-auth-name>}" under the target service’s auth block in the MCP configuration. The MCP’s top-level bucket selects where the source pair is stored. The source service must be workspace-enabled, but it does not need to expose operations through the MCP. The resulting access, refresh, and ID tokens remain attached to the target service and user. For a standalone CLI connection that needs the same routing without loading an MCP, pass --auth-ref '${bucket.auth.<source-service>.<source-auth-name>}' with the target --type and --auth-name. This initialization/debug command has no SDK or MCP identity selector and does not infer the reference from app identity.

Two ways to bind a token

The choice is made when you issue the token, and it decides who can steer it afterwards.

	Dynamic	Fixed
Who picks the user	The caller, per request, via headers	You, once, at issuance
Client requirement	Must be able to set custom headers	Only needs `Authorization`
Good for	One agent serving many end users	One agent scoped to one customer

Dynamic — the caller names the user

Issue an ordinary token, then send selectors as headers on the MCP connection. Both positional arguments are yours — the server, then a name for this token:

fused-cli mcp token generate <mcp-name-or-id> <token-name>

fused-cli mcp token generate support-agent triage-bot \
  --allow createIssue \
  --expires-in 1h

Authorization: Bearer <MCP execution token>
X-Fused-End-User-Ref: user_123
X-Fused-Resource-ID: <optional connection-resource UUID>

Header	When you need it for physical calls
`X-Fused-End-User-Ref`	Required for connected OAuth or OIDC calls
`X-Fused-Resource-ID`	Required when that connection reaches several provider tenants and none is default

Configure these once on the connection as the routing context for physical calls. A Unified call may instead provide non-secret, target-keyed selectors for the services in its selected graph; a dynamic token honors those selectors at execution time. See call a unified operation.

Fixed — the token names the user

--fixed-binding resolves a service, auth scheme, user, and optional resource at issuance. Caller headers and Unified call selectors cannot override it.

fused-cli mcp token generate support-agent acme-only \
  --expires-in 1h \
  --fixed-binding 'jira,OAuth2,user_123,7d41a8b2-…'

The tuple is service-slug,auth-name,end-user-ref[,resource-id]. Use the same service slug you use in workspace and MCP configuration; internal service UUIDs are never part of this command. Both jira and a provider-qualified slug such as @atlassian/jira use the ordinary workspace service-reference resolver. Repeat the flag once per service/auth pair the token may reach. Different services on one token may intentionally use different end-user references:

fused-cli mcp token generate workspace-agent customer-only \
  --allow listProjects \
  --allow gmail.users.getProfile \
  --fixed-binding 'jira,JiraOAuth,jira-customer-a' \
  --fixed-binding 'gmail,oauth2,google-customer-a'

A token is either fully bound or not issued — there is no partially-bound state to clean up.

Reach for fixed binding when the MCP client only supports an Authorization header, or whenever a token must be permanently limited to one customer’s account. It removes a whole class of “the agent acted as the wrong user” mistakes, because the caller has no say in it.

Flags

`mcp token generate`

Flag	What it does	Example
`--fixed-binding`	Pins `service-slug,auth-name,end-user-ref[,resource-id]`; repeatable	`fused-cli mcp token generate support acme --fixed-binding 'jira,OAuth2,user_123'`
`--allow`	Restricts the token to exact operation IDs	`fused-cli mcp token generate support acme --allow createIssue`
`--expires-in`	Gives the token a lifetime	`fused-cli mcp token generate support acme --expires-in 1h`

When one user has several tenants

A single OAuth token can front several provider sites, shops, or accounts. The Engine discovers them and picks a default when there is exactly one.

fused-cli workspace connection resources list <connection-id> --json
fused-cli workspace connection resources set-default <connection-id> <resource-id>
fused-cli workspace connection resources rediscover <connection-id>

With several resources and no default, a call that names no resource fails with a structured ambiguity error rather than guessing a tenant. Fix it by setting a default, or by passing X-Fused-Resource-ID per call. Find the connection ID with:

fused-cli bucket connections default --service jira,github@v3 --user user_123

Who refreshes the token

Nobody, manually. The Engine refreshes eligible connections at startup and hourly, scheduling from whichever expires first. An expired access token is not a reconnect — the Engine rotates it while the refresh grant is still valid. A connection becomes reconnect_required only when refresh material is missing, expired, revoked, or rejected by the provider. A client with URL elicitation support can present a reconnect link on the affected call. Otherwise, run the same connect flow again for the same bucket, service, auth name, and user reference.

Never treat an unexpected provider 401 or 403 as permission to replay a mutation.

What the agent never sees

The MCP token authenticates the client to the Engine. That is all it does. Provider credentials and OAuth tokens stay in the server’s bucket, are never sent to the MCP client, and never appear in the agent’s context. Do not add a second token format or an MCP-client OAuth flow. SDK and MCP deliberately share one execution-token contract, and provider OAuth stays inside the Engine.

Connect a user's account

The full connect flow, resource selection, and what happens when a grant lapses.

Get Started

Guides

Advanced

Reference

Tokens for OAuth services

Before the token exists

Two ways to bind a token

Dynamic — the caller names the user

Fixed — the token names the user

Flags

`mcp token generate`

When one user has several tenants

Who refreshes the token

What the agent never sees

Connect a user's account

​Before the token exists

​Two ways to bind a token

​Dynamic — the caller names the user

​Fixed — the token names the user

​Flags

​mcp token generate

​When one user has several tenants

​Who refreshes the token

​What the agent never sees

Connect a user's account

Before the token exists

Two ways to bind a token

Dynamic — the caller names the user

Fixed — the token names the user

Flags

`mcp token generate`

When one user has several tenants

Who refreshes the token

What the agent never sees