Caller Context element

The Caller Context element verifies an inbound caller’s credential with one of its authentication methods and populates input.source_auth for policy evaluation. Drop it on the Access Point → Managed Agent edge. A surface has one Caller Context element, which holds one or more methods.

What happens without this element, and when a caller’s credential is missing or invalid, depends on the Access Point’s state. A request carrying credentials for more than one method counts as invalid.

On a public or legacy Access Point, when a caller fails authentication, the gateway forwards its request but leaves out the stored credential it holds for the Target, such as the Managed Agent’s Target Authentication or an A2A Proxy’s Direct Line secret. This holds for direct targets, MCP Proxy and A2A Proxy targets, and requests sent to or received from a connected gateway over Fabric. Most backends then reject the request, so add a policy that denies failed callers when they should be refused at the gateway instead.

Over Fabric, the sending gateway removes the credential header its own Caller Context read, and any Authorization header from the caller, before forwarding. The receiving surface authenticates the partner’s request with its own Caller Context. When that surface is closed, it answers 503 if it has no Caller Context, and 401 if the credential it reads was removed on the way. Give the receiving surface a credential it can check: set it in the sending Managed Agent’s Target Authentication, or have callers send it in a header that the sending surface’s Caller Context doesn’t read.

Authentication methods

A Caller Context element holds one or more authentication methods. With several, one surface accepts more than one kind of credential, for example a JWT from internal users and an API key from partner agents, and the managed agent keeps one identity. A new Caller Context element starts with one JWT Bearer method.

Method list

The sidebar panel lists the methods under Authentication methods, one row each:

Select Add method below the list to add a method: JWT Bearer, API Key (secret store), API Key (provider), or DID Auth. mTLS (Mutual TLS) is listed but disabled. The new method goes to the end of the list with its default settings, and the fullscreen editor opens on it.

The fullscreen editor, Caller Context Extraction, shows the same list with two more controls on each row:

• Make primary, on every method after the first, moves that method to the top of the list. It is disabled while authorization server discovery is on.
• The remove button (trash icon) deletes the method. It is disabled when the element has only one method.

Below the list, Method settings shows the Authentication Method dropdown for the selected method, and that method’s fields, described in the sections below. The dropdown offers the same options as Add method.

How the gateway selects a method

For each request, the gateway selects one method and verifies the credential with that method only:

• A request carrying one method’s credential is verified by that method. A credential counts when its header is present and not empty, or for JWT Bearer, when the Token Header holds a token in the method’s Scheme. A value in another scheme on the same header, such as an Authorization: Payment credential, is not a JWT.
• A request carrying no method’s credential is checked by the primary method, so it fails as a missing credential of that method.
• A credential the selected method rejects is not retried with another method.
• A request carrying credentials for more than one method fails source authentication, and no method verifies either credential. This includes a client’s own Bearer token sent beside an API key, when a JWT Bearer method reads Authorization.

A request that fails, including one carrying credentials for two methods, is handled as in the table above. On a closed Access Point, it is refused with 401 before policy runs. On a public or legacy Access Point, it reaches policy with input.source_auth.method set to failed. Its attempted_method names the method selected for the request, the primary method when the request carried credentials for two. The gateway records a request carrying two credentials in its audit log with the reason ambiguous_credentials.

Policy sees the method that verified the caller as input.source_auth.method, so a rule can treat JWT callers and API key callers differently. See input.source_auth.

Apart from the primary method, the order of the methods has no effect.

Rules for saving several methods

The gateway selects a method by where its credential is, so each method needs its own location. A method that breaks one of these rules shows the message on its row, and the surface can’t be saved until it is fixed:

The numbers and the location in each message name the methods involved. A method missing a required field also shows a problem, such as “JWT strategy must be selected” or “API key secret must be selected”.

Two Identity element types add a rule of their own: From JWT Claims needs every method to be JWT Bearer, and From API Key on the inbound caller slot needs every method to be API Key (secret store) or API Key (provider). See Identity element.

Method: JWT Bearer

Validates incoming requests using a bearer token verified against a configured JWT verification strategy. A request whose Token Header carries more than one token in the method’s Scheme fails verification. On a closed Access Point, the gateway answers a request whose token is missing or invalid with 401 and a WWW-Authenticate: Bearer header, before policy runs. On a public or legacy Access Point, it is recorded as a failed authentication attempt on input.source_auth, and a policy rule must check that field to deny the caller. With authorization server discovery on, the gateway answers such a request with 401 and its challenge in every state. A server-side failure, such as a JWT verification strategy that no longer exists, returns 500 Internal Server Error instead.

A token is refused when it is expired, or when its nbf (not before) time is more than 60 seconds in the future. See Token validation sequence for every check.

Authorization server discovery

On an MCP surface, when the first method is JWT Bearer, Method 1 settings also shows an Authorization server discovery switch. Turn it on when callers use standard MCP clients that sign users in at your own authorization server: the gateway then tells those clients where to get a token. The compact panel shows whether discovery is on and how many authorization servers it lists.

Discovery belongs to the first method and keeps it primary. While discovery is on, Make primary is disabled on the other rows, and a later method can’t be JWT Bearer. Removing the first method, or changing its Authentication Method away from JWT Bearer, turns discovery off.

While discovery is on:

• The gateway publishes a protected resource metadata document (RFC 9728) at /.well-known/oauth-protected-resource followed by the Access Point route, on the Access Point’s listener. Any web origin can read it, so browser-based MCP clients can fetch it.
• A request whose token is missing or refused gets HTTP 401 with a WWW-Authenticate: Bearer challenge whose resource_metadata parameter points at the document. A request carrying credentials for more than one method fails as the first method and gets the same challenge. A credential of another method that fails gets a plain 401. The gateway answers before policy runs, so a policy rule for failed callers is unnecessary on this surface.
• A token is accepted only when its aud claim is the resource URL advertised for the route called. Accepted Audiences stays empty and can’t be edited.
• Token Header is fixed to Authorization and Scheme to Bearer.
• Forward token header to managed agent stays off, because MCP forbids passing the caller’s token to the upstream server.
• Over Fabric, a receiving gateway answers a failed token with 401 but without resource_metadata, because the sending gateway removes the caller’s own token before forwarding.

Method: API Key (secret store)

Compares the presented credential against a stored secret.

Method: API Key (provider)

Delegates API key verification to this surface itself. Create API keys from the API Keys page using this surface’s ID as the agent. No additional configuration is required here.

Method: DID Auth

Callers authenticate with a signed session token tied to their decentralized identifier (DID). Reach for this when the caller’s identity is already a DID and you want the gateway to bind that identity, rather than a bearer token or API key, to the request.

Method: mTLS

Trusts the TLS-terminated client certificate presented by the caller.

Related

• Accept JWTs and API keys on one surface: add an API key method beside JWT Bearer so one surface serves internal and partner callers.
• OPA policies reference: how input.source_auth is populated for policies.
• JWT Verification Strategies reference: strategy fields and token validation sequence.
• API keys reference: creating and managing API keys for provider mode.
• Enable authorization server discovery for MCP clients: turn on authorization server discovery for an MCP surface.
• Access Point reference: inbound configuration and how Caller Context attaches.