# Token exchange

How the gateway turns the agent's token into one meant for a product (RFC 8693), and every check Buun Identity makes before it does. A product never takes part in the trade; it only checks the token it is sent.

## The request

Only one client may trade: the gateway's own, confidential, a Buun Group service, with `acts_for` set to the gateway's address.

```http
POST /oauth/token
Authorization: Basic <gateway exchange client id and secret>
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the agent's access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://mcp.plotwork.dev/mcp-oauth
```

```json
{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid profile email"
}
```

## The checks, in order

| Check | Refused with |
|---|---|
| The client is confidential, a Buun Group service, and has `acts_for` | `unauthorized_client` |
| `subject_token` is there, of type `access_token` | `invalid_request` |
| `resource` is a registered resource server with a product | `invalid_target` |
| The subject token is signed by Buun Identity, not expired, and its `aud` is exactly the client's `acts_for` | `invalid_grant` |
| The person exists and is not suspended | `invalid_grant` |
| The agent's grant is still live: the person has not disconnected it in the portal | `invalid_grant` |
| The person holds an active plan for that product now | `invalid_grant` |

Every `invalid_grant` has the same message. Buun Identity logs which check failed as `oauth.exchange_refused` with a `reason` of `subject`, `account`, `grant` or `plan`, and never the token.

## The token it answers

| Claim | Value |
|---|---|
| `aud` | The product's MCP endpoint, the `resource` asked for |
| `sub` | The person |
| `client_id` | The gateway's exchange client |
| `act` | `{ "sub": "<the gateway's exchange client>" }` |
| `scope` | The agent's scopes among `openid profile email orgs`. Never `offline_access` |
| `exp` | 15 minutes, or when the agent's own token ends, whichever is first |

There is no refresh token and nothing is stored. The gateway keeps a traded token in memory until a minute before it ends, keyed by a hash of the agent's token and the product, and trades again after that, or at once when the product answers 401.

## Turning it on for a product

| Where | What |
|---|---|
| The product | Accept the token: [Accepting Buun Identity tokens](https://developers.buungroup.com/mcp/accepting-tokens) |
| Buun Identity | A resource server for the product's MCP endpoint, with the product set, from the staff console |
| The gateway | `acceptsIdentityTokens: true` on the product in the catalogue, and `IDENTITY_EXCHANGE_CLIENT_ID` and `IDENTITY_EXCHANGE_SECRET` set on the Worker |

Without the exchange client, every product keeps its own sign-in, whatever the catalogue says.

Source: https://developers.buungroup.com/mcp/token-exchange
