Source authentication

Every surface authenticates its inbound caller through a single method, chosen on the surface’s Caller Authentication panel. This page documents all four methods, where the values each one needs come from, and the identity each produces after a successful check. For the conceptual model, see Security and access control.

Where to find it: Surface editor → Caller Authentication panel.

Authentication methods

• JWT bearer fits best when your caller already gets tokens from an identity provider such as Entra ID, Auth0, or Okta: you verify a token you didn’t issue, and its claims flow through as the caller’s identity.
• API key is the fastest option to set up, a simple shared secret you create and check yourself, with nothing more to it.
• Reach for API Key Provider when per-caller keys, each with its own expiry, rotation, and revocation, matter more than a single shared credential.
• mTLS makes the certificate itself the proof, which is the strongest option because there’s nothing for a caller to leak or forget to send. It’s overkill, though, for most surfaces where a token or key already does the job.

Whichever method is configured, the credential it consumes (the JWT, the header value, etc.) is stripped from the request before it is forwarded upstream: the authorization header for JWT bearer; the extraction header for the two API-key methods; nothing for mTLS, since the certificate never travels as a header on the forwarded request.

JWT bearer

Verifies a signed token against a registered strategy and produces the caller’s identity from its claims. This reuses an identity your caller already authenticates with elsewhere: no separate credential to issue, and the token’s claims (subject, roles, any custom claim) become available to the request and to downstream policy checks.

• Register the strategy with the issuer URL and JWKS endpoint from your identity provider’s own admin console (Entra ID, Auth0, Okta, and similar providers all publish both), then pick it from the JWT Verification Strategy dropdown.
• Accepted Audiences should match the value your identity provider issues for this API, normally whatever’s configured on the OAuth client registration the caller uses. It only needs to stay empty if your OAuth server’s access tokens omit aud entirely.
• Token Header and Scheme rarely need to change from their defaults (Authorization / Bearer); adjust them only if your caller sends the token somewhere non-standard.

On success this produces the caller’s identity: the token’s subject claim and the full decoded claim set.

API key

Validates a presented key against a secret’s value. It’s the simplest way to gate a surface behind a single shared credential, pairing it with a secret you already created and requiring no separate identity system.

• Choose HTTP Header for a normal REST/HTTP caller, or Protocol-Specific for MCP or A2A traffic, where the key is read from the protocol’s own metadata rather than a header. No header name is needed for this option, even though the panel still shows a text field next to it.
• Create the secret first on the Secrets page, pasting in the credential you want a caller to present, then reference it here by name. A comma-separated value lets more than one key work.
• Match HTTP Header Name to whatever your caller actually sends, e.g. X-API-Key or Authorization.

On success this produces the caller’s identity: the human-readable name of the matched secret.

API Key Provider

Validates a presented key against the managed API key store instead of a plain secret. Each caller gets its own key: individually expired, rotated, or revoked, with an audit trail of who issued it and when.

• Choosing this over a plain API key pays off once you need to tell callers apart, or to expire and revoke one caller’s access without affecting anyone else’s.
• Create the matching keys on the API Keys page using this surface as the agent. Agent ID here comes pre-filled with this surface’s own ID and is read-only.

On success this also produces the caller’s identity, in the same shape.

mTLS

Validates a client certificate captured either from a direct TLS handshake or from a trusted forwarded-client-cert (XFCC) header. The certificate itself is the credential, so there’s nothing for a caller to leak or forget to send.

• Upload the certificate you expect the caller to present, then choose it from the Client Certificate dropdown. The dashboard matches by exact fingerprint (“Pinned” trust), not a CA chain.
• If you need CA-chain trust, revocation checking (CRL/OCSP), or an identity binding other than the fingerprint (Subject CN, a SAN, or a specific Subject DN field), use the management API instead; the dashboard doesn’t expose those modes.

The dashboard configures single-certificate (“Pinned”) trust only, with the caller’s identity always derived from the certificate’s fingerprint.

Related

• Security and access control: the conceptual model for source authentication, RBAC, and secrets together.
• Core configuration: optional configuration blocks: where source authentication sits among a surface’s other optional blocks.
• OPA policies: the caller identity this authentication step establishes, including an mTLS caller’s certificate fingerprint, is what a policy’s input.source_auth evaluates against.
• Secrets and API keys: the two credential stores the API key and API Key Provider methods validate against.
• RBAC: the administrative role ladder that governs who can create and manage the JWT strategies, secrets, API keys, and certificates these methods depend on, separate from this runtime authentication.