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
Verified : Code examples on this page have been automatically tested and verified.Verify JWT tokens from incoming requests using JWKS and configured issuers.
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.
When a jwtAuth policy lists more than one entry under providers, agentgateway tries each provider whose issuer matches the token’s iss claim and whose JWKS contains the token’s kid, in the listed order. The first provider that validates the signature and claims accepts the token. As a result, multiple issuers can publish the same kid value, and several providers can share one issuer, such as providers with different audiences.
If a token includes a not-before claim (nbf), agentgateway rejects the token when the nbf value is more than 60 seconds in the future. The nbf claim is optional by default. To require it, add nbf to requiredClaims.
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. In an MCP route, this setting also letsmcpAuthenticationvalidate the same token afterjwtAuthvalidates the 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.
You can configure JWT authentication in the UI or in your configuration file.
The following steps add the same jwtAuth policy as the Simplified (LLM) example in the Config file tab.
Save your JWKS to a file on the gateway host, such as
./manifests/jwt/pub-key. The file must exist before you save the policy. Otherwise, the save fails with afailed to load JWKSerror.Create a configuration with an LLM model, but no JWT policy. You add the policy in the UI.
# yaml-language-server: $schema=https://agentgateway.dev/schema/config llm: models: - name: "*" provider: openAI params: apiKey: "$OPENAI_API_KEY"Start agentgateway with this configuration.
Open http://localhost:15000/ui/llm/policies (LLM > Policies), and click the JWT auth tile.
In the Enforcement section, select Strict for the Validation mode.
In the Signing keys section, select Local file for the JWKS source. Then, enter
./manifests/jwt/pub-keyfor the JWKS file. A relative path is resolved from the folder that agentgateway runs from.In the Token validation section, fill out the following fields.
- Enter
agentgateway.devfor the Issuer. - In Audiences, enter
test.agentgateway.dev, and click Add. - Keep the default Required claims selection,
exp.
- Enter
Click Save policy.
The UI also writes an empty jwtValidationOptions field, which keeps the default required claims. The form supports one issuer. To configure more than one entry under providers, use the Raw icon (<>) in the drawer header or the Config file tab.
You can also add a JWT policy in MCP > Policies, or in the Gateway policies section of a gateway in Traffic > Gateways.
Whether the UI can save depends on your storage mode. For more information, see Save changes from the UI.
It is common to pair jwtAuth with authorization, using the claims from the verified JWT.
For example:
The following steps add the authorization policy from the Simplified (LLM) example in the Config file tab. First, add the jwtAuth policy with the JWT auth tile. For the steps, see the UI tab that adds the jwtAuth policy on this page.
Open http://localhost:15000/ui/llm/policies (LLM > Policies), and click the Authorization tile.
Click Add rule. Keep the Allow effect.
Replace the example expression with
request.path == "/admin" && jwt.groups.contains("admins").
Click Save policy.
In MCP > Policies, add the same two policies. For the Routing-based example, add the JWT auth policy in the gateway’s Gateway policies section. Then, add the Authorization policy in the Route policies section of a named route.
