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
gateways:
  default:
    port: 3000
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

Signed JWT

Some upstreams do not accept a durable credential at all. The Snowflake SQL API, for example, requires a JWT that is signed with the caller’s private key on each call. With jwtSign, agentgateway mints the token itself: it loads a PEM-encoded RSA or EC private key, signs a JWT that carries the claims you configure, and writes that token to each request that it forwards to the backend. Nothing is cached, so agentgateway signs every request afresh.

backendAuth:
  jwtSign:
    signingKey:
      file: /path/to/signing-key.pem
    alg: ES256
    kid: my-signing-key
    claims:
      iss: MYACCOUNT.MYUSER.SHA256:my-public-key-fingerprint
      sub: MYACCOUNT.MYUSER
      aud: https://myaccount.snowflakecomputing.com
    ttl: 60s

Only signingKey is required. A policy that sets nothing else signs with RS256 and a 300-second lifetime, and writes the token to the Authorization header.

The signer owns the time claims. Agentgateway always sets iat and exp, and backdates iat by 10 seconds so that a validator whose clock trails the proxy still accepts a freshly minted token. A decoded token therefore spans the ttl plus 10 seconds, and never carries an nbf claim. Setting iat, exp, or nbf under claims is rejected when the configuration loads.

Error: jwtSign claim "iat" is reserved for the signer and cannot be configured

An alg that disagrees with the key family is rejected the same way, so a mismatch surfaces before the proxy serves traffic.

Error: failed to parse jwtSign signingKey: failed to load RSA signing key

Token exchange methods

Instead of attaching a fixed credential, agentgateway can exchange the incoming request’s credential for a new, backend-specific token at an OAuth authorization server before forwarding the request.