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.

Attaches to: ListenerRoute

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 tokens**JWT (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).
• The audiences lists allowed audience values (aud)
• The jwks defines the list of public keys to verify against.

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!

# 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"

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  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
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    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
routes:
- backends:
  - host: localhost:8080

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"

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  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")'
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    jwtAuth:
      mode: strict
      issuer: agentgateway.dev
      audiences: [test.agentgateway.dev]
      jwks:
        file: ./manifests/jwt/pub-key
routes:
- policies:
    authorization:
      rules:
      - allow: 'request.path == "/admin" && jwt.groups.contains("admins")'
  backends:
  - host: localhost:8080