Token exchange
The agent exchanges the subject token for a short Xokepoint token that carries the subject and the agent.
This page is the headless mode. In the interactive mode, a coding harness gets the same kind of token through an authorization code login and a refresh token (Connect a coding harness); the token table below applies to both modes.
The agent never calls tools with the token that the IdP issued to the user. It takes that token to the Xokepoint authorization server (AS) and exchanges it for another one, issued by Xokepoint, that carries the subject and the agent. The exchange follows OAuth 2.0 Token Exchange (RFC 8693).
Three checks happen before any token leaves: the agent is who it says it is (client assertion with private_key_jwt), the user token is valid (the same identity connection that the PEP uses) and the user delegated to this agent (OpenFGA). If any of them fails, the AS answers with an RFC 6749 §5.2 error and issues nothing. The error_description holds only the Reference code of the refusal, never the reason (Quick incident). If the instance asked for limits, the AS also checks their shape and that the agent can call each tool; if not, it answers invalid_authorization_details.
The issued token
The token follows the JWT access token profile of RFC 9068:
| Claim | Value |
|---|---|
header typ | at+jwt, signed with ES256 |
iss | The Xokepoint AS, one issuer for each workspace and environment: <origin>/as/<workspace>/<environment> |
aud | The MCP ingress of that environment: <origin>/api/v1/mcp/<workspace>/<environment> |
sub | The subject |
act.sub | The agent |
chokepoint_subject | The identity connection and the kind (person or service) of the subject, and presence: headless for a token exchange, interactive for a harness login |
chokepoint_subject.grant_id | Interactive only: the grant of the machine that logged in, so that one machine can be revoked alone |
cnf.jkt | Interactive only, when the harness used DPoP: the thumbprint of its key (RFC 9449) |
exp | At most 5 minutes, never after the end of the delegation or the consent |
authorization_details | The limits of the instance, when it asked for them (RFC 9396) |
The audience is the ingress of one environment, not "Xokepoint" in general, so a token issued for staging is refused in production even before the signature check gets there.
Instances of the same agent run at the same time, and each one makes its own exchange. An instance can ask for its own limits, for example max_amount = 100 on refund_payment. They only narrow access, and the signed token makes them tamper-proof. Instance limits covers the format, the rules and how a call condition reads them.
The short lifetime is a design decision, not a limitation. Xokepoint does not synchronize user lifecycle with the IdP. A user disabled in the IdP cannot get a new token, so the next exchange fails and the agent runs out of token within minutes. In the interactive mode, the refresh does not reach the IdP, so other limits apply. Revocation details both paths.
What the exchange does not accept
The headless mode uses one grant: RFC 8693 token exchange, authenticated with private_key_jwt. The interactive grants (authorization_code and refresh_token) are for harnesses and use a client metadata URL instead of a key. A few standard parameters of the token exchange grant are refused on purpose, and an integration that sends them gets an error instead of a silently different token:
| Parameter | Answer | Why |
|---|---|---|
actor_token, actor_token_type | invalid_request | Delegation proven by the IdP (Entra On-Behalf-Of, Okta Cross App Access through an ID-JAG, the act claim in Keycloak) is not supported yet. The agent always proves itself with its own key. |
audience, resource | invalid_target | The token is always for the MCP ingress of the environment. Tokens for customer servers are issued by Xokepoint itself after ALLOW (Upstream authentication). |
scope | invalid_scope | Access is decided by relations and rules on every call, not by scopes in the token (Why ReBAC). |
When delegation proven by the IdP arrives, the check in OpenFGA will still apply: the IdP proves that the person delegated, and Xokepoint still decides whether that delegation is allowed by the customer's policy.
The AS publishes its metadata (RFC 8414) at <origin>/.well-known/oauth-authorization-server/as/<workspace>/<environment>, with the token endpoint, the JWKS URI and authorization_details_types_supported. For the interactive mode it adds the authorization endpoint (<issuer>/authorize), the authorization_code and refresh_token grants, code_challenge_methods_supported: ["S256"], client_id_metadata_document_supported: true and dpop_signing_alg_values_supported.