For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Attach the gateway’s own credential to requests that it forwards to a backend.

Backend authentication is how the gateway proves its own identity to an upstream service. Client authentication is the opposite direction: how a client proves its identity to the gateway. The two are separate settings, and most routes need both.

A request therefore carries up to two credentials at different points in its life. The client sends one to the gateway, and the gateway sends a different one to the backend. What connects them is that the client credential is often what the gateway uses to get the backend credential.

Choose a method

Start from what the upstream expects, not from what the client sends.

The families in more detail:

• Static key. The simplest case, and the right one whenever the backend issues you a long-lived credential. Prefer a Secret or a file over an inline value, so that the credential is not stored in the configuration.
• Passthrough. Sends the client credential on to the backend unchanged. Use it when the backend validates the same credential that the gateway validated, such as two services that trust the same issuer.
• Cloud provider credentials. The gateway authenticates as itself, using the identity of the workload it runs as. This is the method to reach for on a managed cluster, because it needs no stored secret: the cloud supplies the identity and the gateway exchanges it for a token. Each provider also accepts an explicit credential when the ambient identity is not the one you want.
• Signed JWT. For an upstream that rejects durable credentials outright and wants a fresh keypair-signed JWT on each call. The Snowflake SQL API is the common example.
• OAuth token exchange. Narrows or re-scopes the client’s credential. Use it when the client identity should reach the backend, but not the client’s original token, and when one authorization server can issue the new token.
• Cross App Access. Token exchange across a trust boundary, using the OAuth Identity Assertion Authorization Grant. The identity provider that authenticated the user and the authorization server that guards the resource are different parties, so the gateway performs two exchanges and holds a client registration at each. For a single-leg exchange, use OAuth token exchange instead.

Two methods are not available everywhere. GitHub Copilot works in the standalone binary only, and Signed JWT arrived in 1.5.x. For the full matrix, see Method availability.

Combine methods

A policy sets at most one of the methods above. They are alternatives, not layers, and configuring two is rejected rather than applied in some order.

One mechanism is additive. A credentials list injects extra credentials, each to its own location, and it works either on its own or alongside a primary method. Use it for an upstream that wants two credentials on the same request, such as a bearer token and a subscription key.

Backend authentication and client authentication

The two directions interact in one way that is easy to miss: a client authentication policy removes the credential it validates.

A JWT, API key, or basic auth policy reads the client credential from a location, validates it, and then strips it from the request so the backend never sees it. That is usually what you want. It also means the credential is gone by the time backend authentication runs, which matters for two of the methods:

• Passthrough puts it back. The method exists for exactly this reason. On a route with no client authentication policy, passthrough does nothing, because nothing removed the credential in the first place.
• Token exchange and Cross App Access read the request. Both take the subject token from a location on the incoming request, defaulting to the Authorization header with a Bearer prefix. If a client authentication policy on the same route has already stripped that header, the exchange finds nothing to exchange.

debug http::auth::oauth oauth token exchange subject token missing source=Header { name: "authorization", prefix: Some("Bearer ") }

The other methods do not read the client credential at all, so they compose with any client authentication policy without further thought.

Backend authentication is not authorization

Backend authentication decides what credential the gateway sends. It does not decide who is allowed through. A route that attaches a static key to every backend request still forwards every request that reaches it.

To decide which callers are allowed, and which tools or models they may reach, use an authorization policy alongside backend authentication. The two are complementary: authorization runs on the way in, backend authentication on the way out.

Configure backend authentication

In the standalone binary, backend authentication is the backendAuth policy. Attach it to one backend, or to a route so that it covers every backend on that route.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
routes:
- backends:
  - host: backend.example.com:443
    policies:
      backendAuth:
        key:
          value: $MY_API_KEY

For how agentgateway resolves a policy that is set at more than one level, see Attachment points.

Next

Each method has its own page.

For the client side of authentication, see JWT authentication, API Key authentication, and Basic authentication. To control which callers are allowed through, see HTTP authorization and MCP authorization.

Method availability and field differences

The standalone binary and Kubernetes configure the same features, but they do not use the same field names, and in several places they do not use the same shape either. Expand the following section before you copy a configuration block from one mode to the other.