> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens for OAuth services

> Give an agent access to a provider that acts on behalf of individual users.

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](/docs/mcp/use-the-server/provider-oauth). A fixed token requires the connection to exist when you issue it. To connect beforehand, follow these steps:

<Steps>
  <Step title="Register the OAuth app">
    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.

    ```bash theme={null}
    fused-cli secret set jira --bucket default
    ```

    Choose the OAuth method when prompted. For automation, use the explicit
    [`--no-input --value-stdin` form](/docs/bucket/connect-user-accounts#store-the-oauth-app-credentials).
  </Step>

  <Step title="Connect a user">
    One person's grant against that registration. The `--user-ref` you choose here is the value everything downstream uses.

    ```bash theme={null}
    fused-cli workspace service connect jira \
      --bucket default \
      --user-ref user_123 \
      --scope read:jira-work
    ```
  </Step>
</Steps>

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:

```text theme={null}
fused-cli mcp token generate <mcp-name-or-id> <token-name>
```

```bash theme={null}
fused-cli mcp token generate support-agent triage-bot \
  --allow createIssue \
  --expires-in 1h
```

```text theme={null}
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](/docs/app/unified/call).

### 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.

```bash theme={null}
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:

```bash theme={null}
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.

<Note>
  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.
</Note>

## 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.

```bash theme={null}
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:

```bash theme={null}
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](/docs/mcp/use-the-server/provider-oauth) 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.

<Warning>
  Never treat an unexpected provider 401 or 403 as permission to replay a mutation.
</Warning>

## 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.

<Card title="Connect a user's account" icon="user-check" href="/docs/bucket/connect-user-accounts">
  The full connect flow, resource selection, and what happens when a grant lapses.
</Card>