Skip to navigation

Authenticate requests with JWT Auth

Key Auth and JWT Auth are the two main ways to authenticate callers on a route. Key Auth checks a gateway key. JWT Auth checks a JSON Web Token (JWT) that your identity provider (IdP), such as Okta, issued. The gateway validates the token, reads its claims, and passes them on, so that other plugins can enforce policy on them. This topic explains how JWT Auth works and how to combine it with the Agent Scope Gate plugin to limit which MCP tools a user can see.

JWT Auth isn’t available when Postman hosts your data plane. It validates tokens against an identity provider that you register with the gateway, and the console shows a warning on the plugin form when you use a Postman-hosted data plane. For more information, see Choose a deployment model.

Understand JWT Auth

The plugin validates each token against the signing keys that your identity provider publishes. If the token is valid, the gateway treats the request as authenticated and maps claims from the token to the caller’s identity. Other plugins on the route can then use those claims.

Choose JWT Auth over Key Auth when your users or agents already sign in through an identity provider and you want the gateway to use that identity instead of a separate gateway key.

Configure JWT Auth

To add JWT Auth to a route, do the following:

  1. Select Plugins, find JWT Auth in the Auth category, and then select Use.

  2. Enter a Name, set Scope kind to route, and set Scope name to the route that you want to protect.

  3. In Identity provider, select the identity provider that you registered with the gateway. This field is required. An instance without an identity provider doesn’t authenticate requests.

  4. Optionally, open Advanced settings and adjust the following settings:

    SettingWhat it does
    Token sourcesWhere the gateway reads the token, in order. The first match wins. Leave it empty to read a bearer token from the Authorization header.
    Subject claim, Principal claim, Kind claim, Scopes claim, Tenant claim, User claim, Session claim, Installation claim, and Consumer type claimThe names of the claims that the gateway reads. Each has a default, for example sub for Subject claim and scopes for Scopes claim.
  5. Select Save.

If you read the token from a cookie, browsers send it automatically, so the request is exposed to cross-site request forgery. Set the cookie HttpOnly and Secure with SameSite=Lax or Strict, and require a CSRF token on requests that change state. The gateway validates the token but doesn’t add CSRF protection.

Limit MCP tools with claims

The Agent Scope Gate plugin checks the scopes on the authenticated caller before it lets a request through. When the caller’s scopes come from JWT claims, you can control what each person or agent can do.

By default, Agent Scope Gate checks only agent traffic. To also check requests from people, such as users who sign in through your identity provider, select Apply to humans.

To configure the Agent Scope Gate, do the following:

  1. Select Plugins, find Agent Scope Gate, and then select Use.
  2. Enter a Name, and set the scope to the MCP route.
  3. In Required scopes, enter the scopes that the caller must have, as a comma-separated list, for example workspace:read, agent:run.
  4. In Scope match, choose whether the caller needs all of the scopes or any of them.
  5. To check people as well as agents, select Apply to humans.
  6. Select Save.

You can also require a consumer group with Require consumer group, and allow only certain principal types, such as bot or human, with Allow principal types. A request without the required scopes is rejected.

Set scopes for individual tools

To require different scopes for individual MCP tools, for example a scope that allows delete tools, add a tool_scopes map to the configuration. The form doesn’t show this setting, so select Edit as JSON and add it there. For example:

{
"tool_scopes": {
"delete_dashboard": ["agent:dangerous"]
}
}

Tool scope match controls whether a caller needs all of a tool’s scopes or any of them. A call to a tool without its scopes is rejected. For agents, the gateway also hides those tools from the tool list. People still see every tool in the list, but with Apply to humans selected, their calls to a tool without its scopes are rejected.

Next steps