# Secure Agents with JWT Authentication

JWT authentication protects platform-hosted API agent endpoints at the gateway. When enabled, callers must send a valid JWT, by default in the `Authorization: Bearer <token>` header. The gateway validates the token's issuer, signature, and expiry against the [identity providers](/agent-manager/docs/next/guides/configure-identity-providers-at-the-gateway/.md) you select for the agent, and its `aud` claim if you configure audiences.

JWT authentication and [API key security](/agent-manager/docs/next/guides/secure-agent-endpoints-with-api-keys/.md) are mutually exclusive — an agent uses one or the other, not both.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* A platform-hosted API agent created in a project.
* At least one [identity provider configured](/agent-manager/docs/next/guides/configure-identity-providers-at-the-gateway/.md) on the environment's gateway.

## Step 1: Enable JWT Authentication During Deployment[​](#step-1-enable-jwt-authentication-during-deployment "Direct link to Step 1: Enable JWT Authentication During Deployment")

1. Open the AMP Console and select your project.
2. Open the API agent you want to secure.
3. Click **Deploy**, then **Configure & Deploy**.
4. In the deploy drawer, under **Endpoint Authentication**, select **OAuth**.

## Step 2: Configure JWT Authentication[​](#step-2-configure-jwt-authentication "Direct link to Step 2: Configure JWT Authentication")

1. **Identity Providers** (required) — select one or more providers whose tokens the gateway should accept for this agent. Every installation ships a bundled identity provider, ThunderID, already registered as `ThunderKeyManager`.
2. **Audiences** (optional) — add accepted token audiences (the `aud` claim). Leave empty to disable audience validation.
3. **Header name** and **Auth header prefix** — the defaults are `Authorization` and `Bearer`. Change them only if your callers send the token differently.
4. **Forward token to upstream** — when on, the validated token header is forwarded to the agent service so it can inspect the token. Turn it off to strip the header before proxying.

## Step 3: Deploy[​](#step-3-deploy "Direct link to Step 3: Deploy")

Deploy the agent to apply the policy.

note

If you change the authentication setting later, redeploy the agent so the gateway policy is updated.

## Get a Token from the Bundled Identity Provider[​](#get-a-token-from-the-bundled-identity-provider "Direct link to Get a Token from the Bundled Identity Provider")

ThunderID runs per environment and is already trusted by that environment's gateway as `ThunderKeyManager`, so you can issue tokens for your callers without adding a provider:

1. Log in to the environment's ThunderID console. See [Access the Environment ThunderID Console](/agent-manager/docs/next/guides/environment-management/.md#access-the-environment-thunderid-console) for the URL, the `admin` username, and the password generated when the environment was created.
2. Create an OAuth application, following ThunderID's [Manage Applications](https://thunderid.dev/docs/v1.0.x/guides/applications/manage-applications/) guide, and use it to obtain tokens for your callers.

## Step 4: Invoke the Agent with a Token[​](#step-4-invoke-the-agent-with-a-token "Direct link to Step 4: Invoke the Agent with a Token")

Send the token in the configured header when calling the deployed agent endpoint:

```
curl -X POST "<agent-invoke-url>" \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer <token>" \

  -d '<request-body>'
```

Replace `<agent-invoke-url>`, `<token>`, and `<request-body>` with the values for your agent. The token must come from one of the agent's configured identity providers.

The example uses the default **Header name** and **Auth header prefix**. If you changed either in Step 2, replace `Authorization` and `Bearer` to match.

## Testing from the Console[​](#testing-from-the-console "Direct link to Testing from the Console")

note

The agent **Test** page is unavailable while JWT authentication is enabled, because the console cannot mint a token for you. Test the endpoint out-of-band with a valid token, as shown in Step 4.

When JWT authentication is enabled, the agent's **API Keys** page also shows as disabled, since JWT authentication and API key security cannot be active at the same time.

## Notes[​](#notes "Direct link to Notes")

* JWT authentication applies to platform-hosted API agents.
* Accepted issuers and audiences come from the [identity providers configured on the gateway](/agent-manager/docs/next/guides/configure-identity-providers-at-the-gateway/.md).
* An agent uses one authentication method at a time — JWT authentication or API key, not both.
* Authentication will be enforced by the gateway based on issuer and audience claims.