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

Backend authentication

Attach authentication tokens to outgoing backend requests.

Attaches to:

Configuration examples

When connecting to a backend, an authentication token can be attached to each request using the backend authentication policy.

Static keys

To attach a static key as an Authorization value, use key:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    backendAuth:
      key:
        value: $MY_API_KEY
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - host: localhost:8080
        policies:
          backendAuth:
            key:
              value: $MY_API_KEY

The remaining examples on this page show only the backendAuth policy. Attach each one to a backend under backends[].policies, as shown in the complete example above.

File path

You can also add keys via a file path.

backendAuth:
  key:
    value:
      file: /path/to/my/key

Authorization location

By default, the proxy retrieves the key from the Authorization header value.

backendAuth:
  key:
    value: $MY_API_KEY
    location:
      # Send as a request header (default)
      header:
        name: authorization
        prefix: "Bearer "

backendAuth:
  key:
    value: $MY_API_KEY
    location:
      # Send as a query parameter
      queryParameter:
        name: api_key

backendAuth:
  key:
    value: $MY_API_KEY
    location:
      # Send as a cookie
      cookie:
        name: api_key

Passthrough

When using any form of incoming authentication, such as JWT, API key, or basic auth, the original credential is removed from the request by default before forwarding to the backend. To pass the original credential through to the backend, use the passthrough method:

backendAuth:
  passthrough: {}

The passthrough method also accepts a location field to specify where to read the credential from:

backendAuth:
  passthrough:
    location:
      header:
        name: authorization
        prefix: "Bearer "

Google credentials

Google Application Default Credentials can also be used, which can be useful when connecting to GCP services:

backendAuth:
  gcp: {}

To request an access token (for most GCP services) or an ID token (for Cloud Run), set the type field:

backendAuth:
  gcp:
    type: AccessToken

backendAuth:
  gcp:
    type: IdToken
    audience: "https://my-cloudrun-service-xyz.run.app"

Credentials are sourced from the environment automatically (for example, via the GOOGLE_APPLICATION_CREDENTIALS environment variable or a metadata server).

AWS credentials

AWS authentication can be used to sign requests to AWS services:

backendAuth:
  aws:
    # Specify access key and session token
    # Alternatively, leaving this empty will use the standard AWS credential lookup (https://docs.aws.amazon.com/sdkref/latest/guide/access.html) based on the environment
    accessKeyId: "$AWS_ACCESS_KEY_ID"
    secretAccessKey: "$AWS_SECRET_ACCESS_KEY"
    sessionToken: "$AWS_SESSION_TOKEN"
    region: us-west-2

Cross App Access (ID-JAG)

The crossAppAccess method implements the OAuth Identity Assertion Authorization Grant, also called “ID-JAG” or “Cross App Access”. With this method, agentgateway calls a downstream API as the authenticated end user, without requiring the user to interactively log in to that downstream app. This pattern is common in agentic scenarios where an agent calls other apps’ APIs on behalf of the user.

The gateway acts as a confidential OAuth client and performs a two-leg exchange on each backend call:

1. Authenticate the user. The inbound request carries the user’s OIDC ID token, validated by the jwtAuth policy. The validated token is the subject of the exchange. The jwtAuth policy must validate an OIDC ID token, not an arbitrary access token, because the identity provider expects an ID token as the subject.
2. Token exchange. The gateway calls the user’s identity provider (IdP) authorization server with an RFC 8693 token exchange and receives an ID-JAG assertion that is bound to the resource authorization server.
3. JWT-bearer grant. The gateway presents the ID-JAG to the resource’s authorization server with an RFC 7523 JWT-bearer grant and receives a Bearer access token that is scoped to the downstream API.
4. Attach and cache. The Bearer token is added as Authorization: Bearer <token> to the upstream request and cached until shortly before it expires.

The following configuration from the traffic-identity-assertion example in the agentgateway repository configures the crossAppAccess method next to the jwtAuth policy that authenticates the user. Note that the gateway requires two separate client registrations, one at the IdP and one at the resource authorization server, each with its own client ID and credentials.

Error: Unable to load code from https://agentgateway.dev/examples/traffic-identity-assertion/config.yaml

Enterprise IdPs such as Okta commonly require the privateKeyJwt client authentication method, in which the gateway authenticates with a signed JWT assertion instead of a client secret. Because token endpoints are configured as backend references rather than raw URLs, privateKeyJwt requires an explicit assertionAudience:

clientAuth:
  clientId: gateway-at-chat
  method: privateKeyJwt
  signingKey:
    file: /path/to/signing-key.pem
  alg: RS256  # one of RS256/RS384/RS512/ES256/ES384
  kid: my-signing-key  # optional `kid` header
  assertionAudience: https://chat.example.com/oauth2/token