For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
JWT authentication
Verify JWT tokens from incoming requests using JWKS and configured issuers.
Verified Code examples on this page have been automatically tested and verified.Note
Agentgateway supports more than one configuration style. Where a feature can also be configured in the simplified llm or mcp modes, the examples on this page show each option in tabs. For more information, see Routing-based configuration.
JWT tokensJWT (JSON Web Token)A compact, URL-safe token format used for securely transmitting information between parties. JWTs are commonly used for authentication and authorization in agentgateway. from incoming requests can be verified.
JWT authentication requires a few parameters:
- The issuer verifies that tokens come from the specified issuer (
iss). Agentgateway rejects a token from another issuer, and it also rejects a token that has noissclaim. - The audiences lists allowed audience values (
aud). The token’saudclaim must contain at least one of these values. Omit the field to accept any audience. An empty list also accepts any audience, and a non-empty list rejects a token that has noaudclaim. - The jwks defines the list of public keys to verify against.
Important
In version 1.4 and earlier, a configured issuer matched only when the iss claim was present, and a non-empty audiences list matched only when the aud claim was present. A token that omitted the claim passed. From version 1.5, each claim is required, so a token that omits it is rejected. Setting requiredClaims: [] does not restore the earlier behavior, because it removes only the claim requirements that you add yourself, not the ones that the configured issuer and audiences imply. If a client sends tokens without an aud claim, remove the audiences field instead of emptying requiredClaims.
Additionally, authentication can run in three different modes:
- Strict: A valid token, issued by a configured issuer, must be present.
- Optional (default): If a token exists, validate it.
Warning: This allows requests without a JWT token! - Permissive: Requests are never rejected. This is useful for usage of claims in later steps (authorization, logging, etc).
Warning: This allows requests without a JWT token!
After it validates a token, agentgateway removes the token from the location that it was read from, so that the backend never receives the client’s credential. Two settings change that.
- Set
preserveToken: trueon thejwtAuthpolicy to leave the validated token where it was found. Use this setting when another policy on the same route reads the token from the request, such as an OAuth token exchange that takes it as the subject token. - Set the
passthroughbackend authentication method to forward the validated token to one backend. Prefer this form when only the backend needs the token, because it does not expose the credential to every policy that runs later.
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
policies:
jwtAuth:
mode: strict
issuer: agentgateway.dev
audiences: [test.agentgateway.dev]
jwks:
# Relative to the folder the binary runs from, not the config file
file: ./manifests/jwt/pub-key
models:
- name: "*"
provider: openAI
params:
apiKey: "$OPENAI_API_KEY"It is common to pair jwtAuth with authorization, using the claims from the verified JWT.
For example:
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
policies:
jwtAuth:
mode: strict
issuer: agentgateway.dev
audiences: [test.agentgateway.dev]
jwks:
file: ./manifests/jwt/pub-key
authorization:
rules:
- allow: 'request.path == "/admin" && jwt.groups.contains("admins")'
models:
- name: "*"
provider: openAI
params:
apiKey: "$OPENAI_API_KEY"