Validate bearer tokens on a surface

Create a JWT verification strategy in the Agent Gateway dashboard and attach it to a surface to validate bearer tokens from callers.

By the end of this guide, you will have a JWT verification strategy configured and attached to a surface so that the gateway validates bearer tokens on every inbound request.

A JWT verification strategy is a reusable configuration that names a trusted issuer and points to that issuer’s signing keys. Surfaces reference the strategy rather than holding issuer details directly. For background on how strategies fit the gateway’s credential model, see Credentials.

Without a strategy, the surface cannot validate bearer tokens. Any request carrying a JWT is rejected unless a valid strategy is attached to the surface.

Use this guide when:

  • You need a surface to accept bearer tokens from an identity provider.
  • You want multiple surfaces to share the same issuer configuration.

Prerequisites

  • A running Agent Gateway instance with the dashboard accessible.
  • Power User or Administrator role on the gateway.
  • The issuer URL of the identity provider that issues the JWTs, for example https://auth.example.com.
  • Either the JWKS URI of the identity provider, or the static JWKS JSON if the provider does not publish a discovery endpoint.
  • A surface to attach the strategy to.

Steps

Create a JWT verification strategy

  1. In the sidebar, select Credentials, then select the JWT Verification tab. Select Add Strategy.

  2. Fill in the strategy fields:

    FieldRequiredDescription
    NameYesA descriptive label, for example Auth0 production.
    Expected issuerYesThe exact iss claim value the JWT must contain. Must match precisely, including the trailing slash if present.
    JWKS sourceYesHow the gateway obtains the public keys. Select Remote or Static.

  3. For a Remote JWKS source, enter the JWKS URI, for example https://auth.example.com/.well-known/jwks.json. The gateway validates the URI is reachable when you save. A green indicator confirms the URI resolved successfully.

    For a Static JWKS source, paste the JWKS JSON directly into the editor. Use this when the identity provider does not expose a JWKS endpoint.

  4. Select Save.

Reference the strategy on a surface

  1. Open the surface you want to protect on the canvas.
  2. From the left-hand palette, drag a Caller Context element onto the surface and drop it between the Access Point and Managed Agent nodes.
  3. Select the Caller Context node to open its config panel.
  4. Set Authentication Method to JWT Bearer.
  5. Select Configure… to open the full configuration editor.
  6. Select your strategy from the JWT Verification Strategy dropdown.
  7. Optionally, add Accepted Audiences to restrict which tokens are accepted. Type an audience value and press Enter. The JWT must contain at least one of the accepted values in its aud claim. Leave empty to accept any audience.
  8. Close the editor and select Save on the canvas.

All requests to this surface now require a valid Authorization: Bearer <token> header. Requests without a valid token receive a 401 Unauthorized response.

Confirm

Test 1: valid token is accepted

Send a request with a valid JWT bearer token to the surface:

curl -k -X POST "https://<GATEWAY_HOST><SURFACE_PATH>" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"message/send","id":1,"params":{}}'

Expected: the gateway accepts the request and forwards it to the surface.

The -k flag disables TLS certificate verification. Use this for local testing only. Remove it in production.

Test 2: missing token returns 401

Send the same request without the Authorization header:

curl -k -X POST "https://<GATEWAY_HOST><SURFACE_PATH>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"message/send","id":1,"params":{}}'

Expected: 401 Unauthorized. The gateway rejected the request because no bearer token was present.

The -k flag disables TLS certificate verification. Use this for local testing only. Remove it in production.

Troubleshooting

SymptomLikely causeFix
JWKS URI validation fails on saveThe URI is unreachable from the gateway’s network.Confirm the URI is publicly accessible and the gateway has outbound HTTP access to it.
Valid tokens return 401The iss claim in the token does not match Expected issuer exactly.Compare the token’s iss claim (decode at jwt.io) against the strategy’s expected issuer value. Check for trailing slash differences.
Token accepted but audience failsThe token’s aud claim does not match the configured accepted values.Either update the accepted audiences list or remove it to accept any audience.
No strategies appear in the JWT Verification Strategy dropdownNo strategies have been created yet.Create at least one strategy first, then return to the surface and open the Caller Context fullscreen editor again.

Next steps

  • Credentials: conceptual overview of JWT verification strategies and how they fit the credential model.
  • Secrets: store credentials for upstream services.