{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Guides","product":"Identity Management","type":"markdown"},"seo":{"title":"Token exchange","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"token-exchange","__idx":0},"children":["Token exchange"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://datatracker.ietf.org/doc/html/rfc8693"},"children":["OAuth 2.0 Token Exchange (RFC 8693)"]}," allows a trusted client to exchange a user token issued to another trusted client, and to act on behalf of that already authenticated user against a different resource. The client presents an existing user token to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/user/oidc.openapi/other/oidctoken"},"children":["Token"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oidc/token"]},") endpoint and receives a new user access token. Mosaic preserves the user as the subject, records the exchanging client as the actor, and recomputes authorization for the target resource."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typical integrations include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Agentic workflows where a backend client orchestrates calls across APIs using the same user context"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Backend-for-frontend (BFF) and API gateway patterns that retarget a user token at a downstream API"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Microservice chains where each service obtains a token for the next resource"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, a chat app authenticates the user and receives an access token intended for an MCP server. MCP servers typically act as a proxy: the MCP server exchanges that token with Mosaic for a new token targeted at a downstream API. The user stays the subject. The MCP server is the actor; the chat app is the source client."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n subgraph left [ ]\n direction TB\n User([\"User\"])\n App[\"Chat app
source client\"]\n Orig[\"Original access token\"]\n User --> App\n App -.-> Orig\n end\n\n subgraph te [Token exchange]\n direction TB\n MCP[\"MCP server
exchanging client (proxy)\"]\n Mosaic[\"Mosaic
Authorization policy\"]\n MCP -->|exchange| Mosaic\n end\n\n subgraph right [ ]\n direction TB\n API[\"API\"]\n New[\"Exchanged access token\"]\n API -.-> New\n end\n\n App -->|original token| MCP\n MCP -->|exchanged token| API\n","diagramHtml":"

exchanged token

original token

API

Exchanged access token

Token exchange

exchange

MCP server
exchanging client (proxy)

Mosaic
Authorization policy

User

Chat app
source client

Original access token

","diagramHtmlDark":"

exchanged token

original token

API

Exchanged access token

Token exchange

exchange

MCP server
exchanging client (proxy)

Mosaic
Authorization policy

User

Chat app
source client

Original access token

"},"children":["flowchart LR\n subgraph left [ ]\n direction TB\n User([\"User\"])\n App[\"Chat app
source client\"]\n Orig[\"Original access token\"]\n User --> App\n App -.-> Orig\n end\n\n subgraph te [Token exchange]\n direction TB\n MCP[\"MCP server
exchanging client (proxy)\"]\n Mosaic[\"Mosaic
Authorization policy\"]\n MCP -->|exchange| Mosaic\n end\n\n subgraph right [ ]\n direction TB\n API[\"API\"]\n New[\"Exchanged access token\"]\n API -.-> New\n end\n\n App -->|original token| MCP\n MCP -->|exchanged token| API\n"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token exchange flow differs from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/delegate_access"},"children":["delegated access"]}," flow, where one user consents so another user can act on their behalf. Token exchange delegates between ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["clients"]}," while the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["user subject stays the same"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token exchange always involves two clients in the same Mosaic application:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Source client"]},": the client the presented token was issued to. It controls which other clients may exchange those tokens."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exchanging client"]},": the client that authenticates to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oidc/token"]},", presents the existing token, and receives the new token. It must be allowed to initiate token exchange."]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant U as User\n participant S as Chat app\n participant E as MCP server\n participant M as Mosaic\n participant R as API\n\n U -->> S: Log in\n Note right of S: Step 2\n S ->> M: Authorization code flow\n M -->> S: User access token\n S -->> E: Present user access token\n Note right of E: Step 3\n E ->> M: POST /oidc/token
grant_type=token-exchange\n M -->> E: New user access token\n E -->> R: Call API with exchanged token\n","diagramHtml":"APIMosaicMCP serverChat appUserAPIMosaicMCP serverChat appUserStep 2Step 3Log inAuthorization code flowUser access tokenPresent user access tokenPOST /oidc/tokengrant_type=token-exchangeNew user access tokenCall API with exchanged token","diagramHtmlDark":"APIMosaicMCP serverChat appUserAPIMosaicMCP serverChat appUserStep 2Step 3Log inAuthorization code flowUser access tokenPresent user access tokenPOST /oidc/tokengrant_type=token-exchangeNew user access tokenCall API with exchanged token"},"children":["sequenceDiagram\n participant U as User\n participant S as Chat app\n participant E as MCP server\n participant M as Mosaic\n participant R as API\n\n U -->> S: Log in\n Note right of S: Step 2\n S ->> M: Authorization code flow\n M -->> S: User access token\n S -->> E: Present user access token\n Note right of E: Step 3\n E ->> M: POST /oidc/token
grant_type=token-exchange\n M -->> E: New user access token\n E -->> R: Call API with exchanged token\n"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The user authenticates with the chat app. The chat app obtains a user access token from Mosaic (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-2-obtain-a-user-access-token"},"children":["Step 2"]},"). The original access token includes:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"sub\": \"user\",\n \"client_id\": \"chat-app\",\n \"scope\": \"read:mcp\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The chat app then presents that token to the MCP server."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The MCP server authenticates to Mosaic and exchanges the token for a new user access token targeted at the API (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-3-exchange-the-token"},"children":["Step 3"]},"). When Mosaic accepts the token exchange request, it:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authenticates the exchanging client using the client’s configured authentication method."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checks that the exchanging client is allowed to perform the exchange flow."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validates the presented access token and resolves the source client from that token (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},")."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checks that the source client allows delegation for this exchanging client."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checks that the exchanging client is allowed to request the target resource."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Grants the intersection of requested scopes and scopes allowed for the exchanging client. Scopes the client is not allowed to have are dropped rather than rejected. Mosaic never grants ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openid"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offline_access"]}," on an exchanged token, even when requested (meaning Mosaic never issues an ID token or refresh token for token-exchanging clients)."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recomputes authorization for the subject user and the target resource. Permissions and scopes that applied only to the previous resource are omitted."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Issues a new user access token whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," is the exchanging client, and records that client in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["act"]}," claim. The exchanged access token includes:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"sub\": \"user\",\n \"client_id\": \"mcp-server\",\n \"scope\": \"read:resource\",\n \"act\": {\n \"sub\": \"mcp-server\",\n \"act\": {\n \"sub\": \"chat-app\"\n }\n }\n}\n","lang":"json"},"children":[]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The MCP server calls the API with the exchanged token."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delegation is evaluated at each exchange. If the chat app allows the MCP server and the MCP server allows another client, that client can exchange a token currently issued to the MCP server even if the chat app does not list it. The chat app does not need to allow that client unless it presents a token whose current ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," is the chat app."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-configure-clients","__idx":2},"children":["Step 1: Configure clients"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"badge-wrapper"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"badge"},"children":["Admin Portal"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you don't already have a Mosaic application, create one first (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/create_new_application"},"children":["Create Mosaic applications"]},") and add clients."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure both sides of the trust relationship in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Applications"]}," > your app > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clients"]},". Edit each OIDC authentication client, open ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Advanced"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Token exchange"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Who configures it"},"children":["Who configures it"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initiate token exchange"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Exchanging client"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allows this client to call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oidc/token"]}," with the token exchange grant. Disabled by default."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delegate tokens issued by this client"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Source client"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Controls which clients may exchange user access tokens issued to this client. Disabled by default (none)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delegate tokens issued by this client"]}," is enabled, choose who may exchange:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["All"]},": every client in the same application, including dynamically registered clients"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Specific clients"]},": manually registered clients you select, and optionally Client Authorities (so clients registered through those authorities can exchange)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the complete client field list, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/configure_oidc_client#step-4---advanced-settings"},"children":["Configure OIDC clients"]},". Note that any changes to token exchange settings (including enabling or disabling exchange, or changing which clients may exchange) take up to 5 minutes to propagate."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Also confirm:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both clients belong to the same application."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The exchanging client includes the target resource under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resources"]},", if you will pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resource"]}," in the request. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/manage_resources"},"children":["Manage resources"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The source client issues JWT access tokens signed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RS256"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PS256"]},". Mosaic rejects opaque source tokens."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-obtain-a-user-access-token","__idx":3},"children":["Step 2: Obtain a user access token"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"badge-wrapper"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"badge"},"children":["client"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token exchange starts from a user access token already issued to the source client. You can obtain that token from any Mosaic API that returns a user access token—for example, an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/auth_oidc"},"children":["OIDC authorization code flow"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the user authenticates, the source client exchanges the authorization code for tokens:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n https://api.transmitsecurity.io/oidc/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d client_id=CHAT_APP_CLIENT_ID \\\n -d client_secret=CHAT_APP_CLIENT_SECRET \\\n -d code=CODE \\\n -d grant_type=authorization_code \\\n -d redirect_uri=REDIRECT_URI\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," from the response as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject_token"]}," in Step 3. Pass it from the source client to the exchanging client over your backend channel."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-exchange-the-token","__idx":4},"children":["Step 3: Exchange the token"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"badge-wrapper"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"badge"},"children":["client"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From the exchanging client's backend, send a POST request to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/user/oidc.openapi/other/oidctoken"},"children":["Token"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oidc/token"]},") endpoint with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urn:ietf:params:oauth:grant-type:token-exchange"]}," and the user access token from Step 2. Authenticate as the exchanging client using its configured method (client secret, private key JWT, or mTLS)."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urn:ietf:params:oauth:grant-type:token-exchange"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject_token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The user access token to exchange. It must have been issued to a different client. An access token issued to the exchanging client itself, client-credentials tokens, ID tokens, and tokens with no user subject are rejected."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject_token_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(Optional) Type of the presented token. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urn:ietf:params:oauth:token-type:access_token"]},". Only access tokens are supported."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resource"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(Optional) Target resource URI. This is what selects the audience of the new token. The URI must be configured as a resource and allowed for the exchanging client. Mosaic does not use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}," to select the target."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(Optional) Space-delimited scopes to request. Mosaic grants the intersection of this list and the scopes allowed for the exchanging client. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openid"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offline_access"]}," are never granted."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n https://api.transmitsecurity.io/oidc/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \\\n -d client_id=MCP_SERVER_CLIENT_ID \\\n -d client_secret=MCP_SERVER_CLIENT_SECRET \\\n -d subject_token=USER_ACCESS_TOKEN \\\n -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \\\n -d resource=https://api.example.com \\\n -d scope=read:resource\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response returns a new user access token. Mosaic does not return an ID token. If the granted scope differs from the requested scope, the response includes the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," that was actually granted."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"issued_token_type\": \"urn:ietf:params:oauth:token-type:access_token\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token exchange never returns a refresh token. If the request includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offline_access"]},", Mosaic drops it from the granted scope and still returns an access token."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the exchanging client is not allowed to use this grant, Mosaic returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unauthorized_client"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the presented token is invalid, the source client does not allow this exchanging client, or the subject cannot be resolved in the exchanging client's application, Mosaic returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_grant"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the exchanging client is not allowed to request the target resource, Mosaic returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_target"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A client cannot exchange an access token issued to itself. Mosaic rejects that request with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_grant"]},". Cross-application exchange is rejected."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specifying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actor_token"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actor_token_type"]}," in the request isn't supported. A request that includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actor_token"]}," is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A subject token that expires during the exchange is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_grant"]}," and the description ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject token has expired"]},"."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resulting-token","__idx":5},"children":["Resulting token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The exchanged token is a new authorization context, not a copy of the presented token."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Claim"},"children":["Claim"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Preserved from the presented token (the user)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The exchanging client."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aud"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The target resource when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resource"]}," is requested."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recomputed for the exchanging client and target resource. Never includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openid"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offline_access"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["act"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nested actor chain. The outermost ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub"]}," is the current exchanging client. The innermost entry is always the source client—the client the original token was issued to, which never performed an exchange itself. Intermediate entries are previous exchanging clients. This innermost source-client entry is a Mosaic extension to RFC 8693."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example after the MCP server exchanges the chat app token:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"sub\": \"user\",\n \"client_id\": \"MCP_SERVER_CLIENT_ID\",\n \"aud\": \"https://api.example.com\",\n \"scope\": \"read:resource\",\n \"act\": {\n \"sub\": \"MCP_SERVER_CLIENT_ID\",\n \"act\": {\n \"sub\": \"CHAT_APP_CLIENT_ID\"\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This records that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the user remains the subject"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the MCP server is the current actor"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the chat app is the client the original token was issued to"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An exchanged token is not an OIDC identity token. Mosaic does not return an ID token or a refresh token from the exchange, does not grant ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openid"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offline_access"]},", and does not return user profile claims from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/userinfo"},"children":["UserInfo"]}," for an exchanged token. Validate the access token as described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/validate_tokens"},"children":["Validate tokens"]},", or call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/token_introspection"},"children":["Introspection"]}," when you need a server-side activity check."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limitations","__idx":6},"children":["Limitations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following RFC 8693 scenarios are not supported:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exchanging SAML assertions, ID tokens, or JWT assertions from external identity providers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Issuing token types other than OAuth 2.0 access tokens (for example, exchanging an access token for an ID token)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delegating across applications or exchanging a token minted for Mosaic management APIs (Admin Portal, tenants, clients, export/import)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Passing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actor_token"]}," (rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]},")"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["SAML clients cannot participate; they have no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oidc/token"]}," endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["act"]}," chain is limited to 10 levels, so at most 9 consecutive exchanges. A subject token at the maximum depth is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]}," and the description ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject token actor chain is at the maximum depth of 10"]},"."]},{"$$mdtype":"Tag","name":"style","attributes":{},"children":["\ntable th:first-of-type {\n width: 25%;\n}\n"]}]},"headings":[{"value":"Token exchange","id":"token-exchange","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Step 1: Configure clients","id":"step-1-configure-clients","depth":2},{"value":"Step 2: Obtain a user access token","id":"step-2-obtain-a-user-access-token","depth":2},{"value":"Step 3: Exchange the token","id":"step-3-exchange-the-token","depth":2},{"value":"Resulting token","id":"resulting-token","depth":2},{"value":"Limitations","id":"limitations","depth":2}],"frontmatter":{"title":"Token exchange","markdown":{"toc":{"depth":2}},"seo":{"title":"Token exchange"}},"lastModified":"2026-10-21T11:53:46.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/user/token_exchange","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}