Skip to main content
Token brokering is an experimental feature — see Experimental Features for important caveats.
Modern applications often need tokens from multiple services — a GitHub token for repository access, a Databricks token for compute, a GCP token for cloud resources. Without token brokering, each client must independently manage credentials and token lifecycles for every upstream service, spreading sensitive token logic across the application landscape. Token brokering solves this by letting the Orchestrator act as a single token endpoint. Clients exchange their Maverics access token for upstream tokens using standard RFC 8693 token exchange, and the Orchestrator handles acquiring the right token from each upstream service. The Orchestrator determines how to fulfill each request based on the tokenBrokering configuration on the OIDC app.
The AI Identity Gateway can act as the token exchange client, brokering tokens on behalf of AI agents. This pattern ensures agents never receive third-party access tokens directly — the gateway makes a just-in-time token exchange and injects the upstream tokens into outbound requests.

​
Flows

Token brokering supports three flows, determined by the mapping’s type field and whether a tokenSource is set.
TypetokenSourceFlowDescription
passthroughrequiredSession PassthroughReturn an upstream token from the user’s session
exchangeomittedFederated ExchangeOrchestrator mints a JWT and exchanges it with an upstream AS
exchangesetBrokered ExchangeForward the user’s IdP token to an upstream AS for exchange

​
Session Passthrough

The simplest flow. The user authenticated to an upstream IdP during login, and the Orchestrator cached their access token in the session. When the client requests a token for that audience, the Orchestrator returns the cached token directly. Trust model: The upstream IdP issued the token to the user during an interactive OAuth consent flow. The Orchestrator returns it from cache — the upstream doesn’t know the Orchestrator exists. When to use: The upstream service accepts standard OAuth tokens but does not support RFC 8693 token exchange. The user must have authenticated to the upstream IdP during their session. Examples: GitHub OAuth Apps, Atlassian 3LO, Google Workspace APIs (Drive, Calendar).

​
Federated Exchange

The Orchestrator mints a short-lived JWT (signed with its own key) and exchanges it with the upstream authorization server via RFC 8693. The upstream AS trusts the Orchestrator as an IdP through a federation policy that validates the JWT signature via the Orchestrator’s OIDC discovery/JWKS endpoints. Trust model: The upstream AS trusts the Orchestrator’s issuer. A federation policy on the upstream maps the Orchestrator’s JWT claims to an upstream identity. When to use: The upstream supports RFC 8693 token exchange with external JWTs. No user interaction with the upstream is required — the trust is configured between the Orchestrator and the upstream AS. Examples: Databricks Workload Identity Federation, GCP Workload Identity Federation.

​
Brokered Exchange

The Orchestrator retrieves the user’s IdP token from the session (like Session Passthrough) and then uses it as the subject_token in an RFC 8693 exchange with the upstream AS (like Federated Exchange). The upstream AS trusts the customer’s IdP directly — the Orchestrator is not in the trust chain. Trust model: The upstream AS trusts the customer’s IdP (e.g., Okta, Entra) directly. The Orchestrator is invisible to the upstream — it forwards the customer’s IdP token. When to use: The upstream supports RFC 8693 with external JWTs, and the customer’s IdP is already configured as a trusted issuer on the upstream. This avoids adding the Orchestrator to the trust chain. Examples: GCP Workload Identity Federation with Okta/Entra as the trusted issuer, Databricks federation with a customer’s IdP.

​
Client Request Format

From the client’s perspective, token brokering is transparent — it uses standard RFC 8693 token exchange against the Orchestrator’s token endpoint with an audience parameter. 
POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id=my-client
&client_secret=<secret>
&subject_token=<maverics-access-token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&audience=https://api.github.com
&scope=read:user repo
The response follows the standard token exchange format: 
{
  "access_token": "<upstream-access-token>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

​
Configuration

Token brokering is configured on an OIDC app under the tokenBrokering field. Each mapping associates an audience with a brokering action.

​
Mapping Fields

FieldTypeRequiredDescription
audiencestringyesThe audience value that triggers this mapping. Must also be listed in the client’s allowedAudiences.
typestringyesThe brokering flow: passthrough or exchange.
passthroughobjectconditionalRequired when type is passthrough.
passthrough.tokenSource.idpstringyesThe IdP whose access token is stored in the user’s session.
exchangeobjectconditionalRequired when type is exchange.
exchange.idpstringyesThe upstream IdP/AS to exchange with.
exchange.typestringnoToken exchange semantics: delegation or impersonation. Defaults to delegation.
exchange.scopestringnoScope to request from the upstream AS. If omitted, client-requested scopes pass through.
exchange.tokenSource.idpstringnoThe IdP whose session token to use as the subject. If omitted, the Orchestrator mints its own JWT.

​
Session Passthrough Example

The user authenticates to GitHub during login. The client exchanges its Maverics token for the user’s GitHub access token.
maverics.yaml
apps:
  - name: github-tools
    type: oidc
    clientID: github-tools
    clientSecret: <github-tools-secret>
    grantTypes:
      - urn:ietf:params:oauth:grant-type:token-exchange
    authentication:
      idps:
        - github
    accessToken:
      type: jwt
    allowedAudiences:
      - "https://api.github.com"
    tokenBrokering:
      mappings:
        - audience: "https://api.github.com"
          type: passthrough
          passthrough:
            tokenSource:
              idp: "github"

​
Authorization

Token brokering integrates with the existing token exchange authorization pipeline. Before any brokering action is taken, the Orchestrator:
  1. Validates client-requested scopes against the client’s customScopes configuration.
  2. Evaluates OPA token minting policies configured on the client’s authorization.tokenMinting.accessToken.policies.
  3. Only if authorized, proceeds with the brokering action.
OPA policies remain the single control point for authorization decisions regardless of the brokering flow.

​
Prerequisites

​
For Passthrough

  • The passthrough.tokenSource.idp must reference a configured connector.
  • The user must complete an interactive OAuth login flow with that IdP during their session so the access token is cached.

​
For Exchange (without tokenSource)

  • The Orchestrator’s OIDC well-known endpoint and JWKS must be publicly reachable so the upstream AS can validate the minted JWT’s signature.
  • The upstream AS must have a federation policy that trusts the Orchestrator’s issuer and maps its JWT claims to an upstream identity.
  • The exchange.idp must reference a configured connector that supports RFC 8693 token exchange.

​
For Exchange (with tokenSource)

  • The exchange.tokenSource.idp must reference a configured connector, and the user must have authenticated to it during their session.
  • The tokenSource IdP’s access token must be a JWT (the upstream validates it via that IdP’s OIDC discovery/JWKS).
  • The upstream AS must have a federation policy that trusts the tokenSource IdP’s issuer directly.
  • The exchange.idp must reference a configured connector that supports RFC 8693 token exchange.

Experimental Features

Overview of all experimental features and important caveats

SSO with OIDC

Configure the Orchestrator as an OIDC Provider

Policies

OPA authorization policies for token minting