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

Send a static credential to a backend, forward the credential that the client sent, or add extra credentials to the request.

Attaches to:

About

Use one of the following backend authentication methods to send a static credential to your backend. The client may already send the credential that the backend expects. If it does not, agentgateway must supply one of its own.

• Static key (key) sends a value that you configure, either inline or from a file on disk. You can also compute the value from the request with a CEL expression.
• Passthrough (passthrough) sends the JWT that the client sent.
• Extra credentials (credentials) adds one or more credentials, each to its own location, either on its own or alongside one of the other two methods.

All of them write the credential to the Authorization header with a Bearer prefix by default. The location field changes where agentgateway writes it.

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.

Read the key from a file

You can also add keys via a file path.

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

Compute the key from the request

Instead of a fixed value, you can compute the credential for each request with a CEL expression. Set expression instead of value. For example, an external authorization policy can return a token for the backend as metadata, and the expression reads the token from the extauthz variable.

backendAuth:
  key:
    # The extAuthz policy on this route sets backend_token in its metadata.
    expression: extauthz.backend_token

Review the following behavior before you use an expression:

• Set exactly one of value or expression. Configuration validation fails if you set both or neither.
• The expression must return a string. If the expression fails or returns another type, agentgateway sends no credential and removes any existing value from the target location. For example, with the default location, the Authorization header, agentgateway removes the Authorization header that the client sent. The client’s header is not used as a fallback. To learn about the default location, see Change the credential location.
• The location field works the same way as it does for a static value.
• A backend that agentgateway reaches through a tunnel does not support expression. Requests to that backend fail.

Change the credential location

By default, agentgateway writes the credential to the Authorization header with a Bearer prefix. Set the location field to write it somewhere else.

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

Pass through client credentials

Any form of incoming authentication removes the original credential from the request by default, before agentgateway forwards it to the backend. That applies to JWT, API key, and basic auth. To send the original credential on to the backend, use the passthrough method.

backendAuth:
  passthrough: {}

The method forwards a JWT only. It re-sends the token that a JWT authentication policy validated on the route. An API key or basic auth credential is still stripped, and passthrough does not add it back.

The passthrough method has no field for where to read the credential from, because agentgateway does not read it from the request at all. It re-sends the token that the jwtAuth policy already validated. The source is therefore wherever that policy’s own location field reads from, which is the Authorization header by default.

The location field on passthrough controls only where agentgateway writes the token on the backend request. That location does not have to be where the client sent it.

backendAuth:
  passthrough:
    location:
      header:
        name: x-forwarded-token

Send more than one credential

Some upstreams want two credentials on the same request, such as a bearer token and a subscription key. The credentials list covers that case. Each entry sets a location and a key, and the list is independent of the primary method, so you can set it on its own or together with one.

backendAuth:
  key:
    value: $MY_API_KEY
  credentials:
  - location:
      header:
        name: x-tenant-key
    key: $MY_TENANT_KEY
  - location:
      queryParameter:
        name: subscription
    key:
      file: /etc/agentgateway/subscription-key

The policy in the example sends three credentials on every request: the Authorization header from key, an x-tenant-key header, and a subscription query parameter.

For example, the following entry sends the sub claim of the validated JWT in an x-user-id header.

backendAuth:
  credentials:
  - location:
      header:
        name: x-user-id
    expression: jwt.sub