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.
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
{
"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 |
| 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.