> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Authenticate requests with JWT Auth

> Authenticate callers with JSON Web Tokens from your identity provider, and use token claims to control which tools an agent can use.

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.

> **Info**
>
> 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 [Deployment options](/get-started/architecture#deployment-options).

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

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

   | Setting           | What it does                                                                                                                                                                                                                        |
   | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Token sources** | Where the gateway reads the token, in order. The first match wins. Leave it empty to read a bearer token from the `Authorization` header.                                                                                           |
   | **Claim fields**  | The names of the claims that the gateway reads for the subject, principal, kind, scopes, tenant, user, session, installation, and consumer type. Each has a default, for example `sub` for the subject and `scopes` for the scopes. |

5. Select **Save**.

> **Warning**
>
> 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.

For example, suppose one user's token has a scope that allows only read tools, and another user's token also allows delete operations. With Agent Scope Gate on an MCP route, the first user sees only the read tools. The second user sees the delete tools as well.

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. Select **Save**.

You can also require a consumer group, allow only certain principal types such as `bot` or `human`, and set different scope requirements for individual tools. A request without the required scopes is rejected.

## Next steps

* To require a gateway key instead, see [Authenticate requests with Key Auth](/fabric/plugins/key-auth).
* To connect an MCP server that this plugin protects, see [Connect an MCP server](/fabric/gateways/mcp-servers).