Credentials

How the gateway stores outbound delegated credentials and uses them to authenticate to external services on behalf of agents and users.

Credentials store the outbound authorisation material the gateway uses to authenticate to external services on an agent’s behalf. Through credential delegation, the gateway acts as a delegate, attaching the right token or key to outbound requests without exposing the underlying secret to the agent.

The dashboard’s Credentials page groups several related but distinct mechanisms under one set of tabs: this page covers Credential Providers and Credential Tokens, the outbound delegation model described below. JWT Verification Strategies validate inbound bearer tokens from callers; see Validate bearer tokens on a surface. STS Clients issue and redeem standards-based exchange tokens so an agent’s identity can be recognised across domains; see Token exchange and ID-JAG.

What a credential is

A credential is a reusable outbound configuration that tells the gateway how to obtain authorisation for calls to an external provider. It is the opposite direction from source authentication on inbound requests.

  • Inbound source authentication verifies who is calling the gateway.
  • Outbound credentials prove the gateway’s right to call external services.

This delegation keeps trust boundaries clean. An agent asks the gateway to perform an external action, and the gateway uses the matching credential to authenticate that outbound call. Tokens are held per acting agent, per represented user, and per provider so each delegation context remains isolated.

Credential types

OAuth 2.0 Authorization Code

Three-legged, user-consented access. Use this when actions must run as a specific end user who has explicitly granted consent.

Typical configuration includes:

  • Authorization endpoint
  • Token endpoint
  • Client identifier
  • Client secret reference from Secrets
  • Callback URL
  • Requested scopes
  • Automatic refresh setting

OAuth 2.0 Client Credentials

Two-legged machine-to-machine access with no end user involved. Use this for service-to-service calls.

Typical configuration includes:

  • Token endpoint
  • Client identifier
  • Client secret reference from Secrets
  • Requested scopes

OAuth 2.0 JWT Bearer

Machine-to-machine access where the gateway signs a JWT and sends it as the grant, with no client secret. A Google service account works this way, for example one that calls Vertex AI Agent Engine. The dashboard lists this type as OAuth 2.0, JWT Bearer (signed JWT grant).

Typical configuration includes:

  • Token endpoint
  • Signing key reference from Secrets
  • Issuer, and optionally a subject
  • Requested scopes

OAuth 2.0 Client Credentials JWT

Machine-to-machine access where the gateway authenticates its client with a signed JWT and a certificate instead of a client secret. An Entra certificate credential works this way. The dashboard lists this type as OAuth 2.0, Client Credentials JWT (certificate, no client secret).

Typical configuration includes:

  • Token endpoint
  • Client identifier
  • Signing key reference from Secrets
  • Certificate reference from Secrets
  • Requested scopes

Signed JWT settings

Both JWT types add a Signed JWT section to the provider form, and its fields depend on the type. Client Credentials JWT also asks for a Client ID Secret, in the OAuth Client Credentials (Secret References) section:

FieldJWT BearerClient Credentials JWT
Signing KeyRequiredRequired
Key IDOptionalOptional
Signing AlgorithmRS256 (default) or ES256PS256 (default) or RS256
AudienceOptional. Leave it empty to use the token endpoint.Optional. Leave it empty to use the token endpoint.
IssuerRequiredNot shown
SubjectRequiredNot shown
CertificateNot shownOptional. Entra needs it.
Client ID SecretNot shownRequired

The Signing Key secret holds a PEM private key. From version 1.0.5, it can instead hold the whole JSON key file of a Google service account, up to 16 KiB. For a JSON key file, set Issuer to the file’s client_email and leave Key ID empty, so the gateway sends the file’s own key ID. With Key ID empty, the JWT Bearer form warns “No key ID is set.” You can ignore that warning for a Google JSON key file, because the gateway sends the key ID from the file. The Client Credentials JWT form warns “Neither a certificate nor a key ID is set.” when both are empty.

Subject is the signed JWT’s sub claim. Its help reads “The sub claim: the user the assertion is for, such as the user a Google service account acts for with domain-wide delegation. Without it, use the service account’s own client_email.” The form marks it as required and saves a JWT Bearer provider only once it is filled in.

For setup steps, see Call an agent protected by Entra or Google OAuth tokens.

API Key

A shared secret used by providers that authenticate requests with a single key. The key value is referenced from Secrets and is never displayed in credential settings.

What the gateway checks when you save or delete a provider

  • Token endpoint: use an https URL. From version 1.0.5, saving a new or changed http token endpoint is refused with “token_endpoint must be an https URL”.
  • Signing key and certificate: the gateway reads the referenced secrets when you save a JWT provider, and refuses a key that cannot sign with the chosen algorithm or a certificate that is not PEM. A wrong format fails the save rather than the first token request.
  • Deleting a provider: a provider that a surface still uses is kept. The dashboard shows “The credential provider is bound by an agent surface; remove the binding first”, followed by the surface ID when you can see that surface, and the status code 409. Remove the binding from that surface, then delete the provider.

Where credentials fit in the gateway

Credentials are consumed on the outbound path, in two ways:

  • Credential Delegation binds a provider to a surface, and the gateway holds a token per caller, as described below.
  • Target Authentication on the Managed Agent or on a Transit Point can name a provider of a type that needs no user: Client Credentials, JWT Bearer, Client Credentials JWT, or API Key. The gateway then sends its own token from that provider on every request to that destination, and on a Managed Agent with a Direct URL endpoint it uses the same token to fetch the agent card.

When a surface forwards a request to an external destination that requires authentication, the gateway:

  1. Locates the credential binding for the acting agent and provider.
  2. Obtains or reuses a valid token for the represented user context.
  3. Attaches the required token or key to the outbound call.

Because credentials are isolated per agent, per user, and per provider, the gateway can delegate many concurrent external interactions while keeping each context’s tokens separate. The surface is not part of that key, so surfaces that share an agent DID also share their callers’ grants. Rotating a provider secret once in Secrets updates every credential that references it.

When a binding applies but the gateway cannot resolve its credential, for example because the provider was deleted or the token request failed, it refuses the request with 503 instead of forwarding it without the credential. A Transit Point also needs both halves of the key before it looks up a grant: an agent identity, and a transit token that names the caller. Without them it refuses the request with 403. See Requirements for a Transit Point with delegated credentials.

How the gateway decides which hop receives a credential

A credential binding carries no destination of its own. Its Required For setting decides which requests it applies to, and the hop decides which bindings are eligible:

  • A request to the surface’s Target can use any binding. A binding limited to specific MCP tools applies only to a tools/call that names one of those tools.
  • A request the surface receives over Fabric from a connected gateway follows the same rule, because it is forwarded only to the surface’s own Target. From version 1.0.4, a binding that applies to such a request needs a caller that the receiving surface verified itself. Without one, the request is refused with 403, which an MCP surface returns as JSON-RPC error -32001. A binding that holds a per-user grant, such as an Authorization Code provider, refuses a partner’s request to the Target the same way.
  • A request through a Transit Point uses only bindings that apply to all outbound requests. Tool-scoped bindings apply to the surface’s Target alone, because a partner upstream names its own tools and a matching name could belong to a different tool.

When a surface has no Credential Delegation bindings, each Transit Point uses only its own outbound credential, and the surface’s Target receives none of them. This keeps a token issued for one destination from reaching another. For the field-level rules, see Outbound binding elements.

How delegated credentials cross Fabric

A route to a connected gateway, on the Target or on a Transit Point, crosses a trust boundary: the remote gateway is a separate system that can use whatever this gateway sends it. For that reason the caller’s delegated access token travels over Fabric only on a route where Send delegated credentials over Fabric is turned on, and the switch is off by default. With it off, the remote gateway receives no delegated credential.

With it on, the access token crosses and the remote gateway can use it until it expires. A Transit Point sends it on every request, A2A and MCP alike. On the Target, only MCP requests that use protocol revision 2026-07-28 carry it. The refresh token stays on this gateway, so consent, refresh, and revocation stay with the gateway that holds the vault entry. The caller’s own inbound token is removed before any request crosses Fabric, whichever way the switch is set. See Transit Points and Managed Agent for where the switch appears.

When a surface is configured for credential delegation and an outbound call requires a credential the vault does not yet hold, the gateway initiates a consent flow. Three modes control how that flow works. The mode is set on the Consent Mode field of the Credential Delegation element in the surface canvas.

Pre-authorize

The gateway enforces that all required credentials are present before any MCP interaction begins. If a credential is missing, the gateway blocks the session at initialisation and returns the relevant authorisation URLs to the caller. The user completes the OAuth flow up-front, before any tool call proceeds.

Use this mode when the client application can display an auth prompt before the session starts and you want to eliminate any mid-session interruption.

On-demand

The session and MCP interaction proceed normally until a tool call requires a credential that is not yet available. The gateway returns HTTP 401 with the authorisation URL in the response body. The client handles the consent flow out-of-band, completes OAuth, and retries the request.

Use this mode when the client application can handle the consent_required response and trigger an external browser redirect.

Elicit (MCP-native)

When a tool call requires a missing credential, the gateway issues a formal MCP elicitation request to the client over the established stream and holds the original tool call open. The client surfaces the consent prompt inline. Once the user completes OAuth through the gateway’s callback listener, the gateway resumes the original call and forwards it with the injected token.

From the perspective of both the agent and the MCP server, the interaction is continuous. Consent is handled in-band without breaking the protocol flow.

Use this mode when the client application supports MCP elicitation and you want consent to feel native to the agent interaction.

An Elicit timeout (default 300 seconds) bounds how long the gateway waits for the client to complete consent before giving up. When the user declines or cancels the prompt, or the timeout passes, the gateway refuses the tool call with 503 and JSON-RPC error -32603. When the user accepts but has not finished signing in, the call gets consent_required with the authorisation URL.

A fallback setting controls what happens when the client doesn’t support elicitation:

  • On demand (signal consent_required) falls back to the On-demand flow.
  • Fail (return not_applicable) refuses the call with 503 and JSON-RPC error -32603. Under this option, a prompt that can’t be delivered, for example because the client has no open stream, is refused the same way.

A binding can also take its grants from another system that runs the consent flow. Such a binding is created through the API, and the dashboard shows it read-only as External consent (set through the API). On a surface’s Target it must be the only binding, on a surface without Transit Points, and changing or removing it revokes its grants.

OAuth callback

In the Pre-authorize, On-demand, and Elicit modes, the gateway acts as the OAuth callback endpoint. The downstream provider redirects to the gateway callback endpoint with the authorisation code, for example https://GATEWAY_HOST/v1/identity/oauth/callback/PROVIDER_ID. The gateway exchanges it for a token, stores it in the delegation vault, and injects it on all subsequent calls. The calling agent never receives or stores the token.

For step-by-step configuration of consent modes and the delegation vault, see Configure per-caller Credential Delegation.

Managing delegated tokens

The Credential Tokens tab under Credentials in the dashboard lists every token currently held in the delegation vault: which agent and caller it is scoped to, the provider, granted scopes, when consent was granted, and when the token was last used.

An administrator can revoke a token from this list without waiting for it to expire, either one entry at a time or in bulk for every provider a specific caller has delegated to. Revoking cuts off delegated access immediately, and the next request for that caller and provider returns consent_required again. Use this when offboarding a caller or responding to a suspected credential compromise.