Authenticate gateway requests with an external IdP

Enterprise Tier

Gateway authentication lets callers that already hold a token from your own identity provider (IdP) reach a project's gateways, without being issued an Agent Router API key first. You configure one JWT provider for the project and describe how its token claims map to an Agent Router principal. The configuration is project-scoped, so it applies to every gateway in the project at once.

Authentication is configured per project because a project is the shared security boundary: the model catalogue, MCP servers, and providers are authored once for the project and inherited by all of its gateways, and identity works the same way. A single provider therefore lets requests fail over between the project's gateways under one identity boundary. This sits alongside API keys rather than replacing them: project API keys continue to authenticate on the Authorization header, while IdP tokens are read from a separate, dedicated header, so both can be used against the same gateway at the same time.

How access control differs from project API keys

Project API keys and IdP authentication gate access in fundamentally different ways, and it is worth being deliberate about the distinction:

Project API keys are per-user grants. A user is provisioned into Agent Router (typically synced from your SSO), granted membership of the project, and issues a key. Access is an explicit grant you manage in the user directory, and the gateway recognises the user because it already knows them.
IdP authentication is attribute-based, and the gateway holds no directory of your external users. You do not pre-grant individual people. Admission is delegated to your IdP (only identities it will mint a token for can get in) and scoped by the identity-mapping rules you define here: a token is admitted only if its claims match a rule (for example an email domain or a group), and a just-in-time rule provisions a principal on first sight, up to its cap. There is no per-user allow-list synced from the user directory; your IdP's membership and the rule's claim pattern are the access boundary.

In practice this means you control who can reach the gateway by managing membership and group assignment in your IdP (together with the rules below), not by granting individual users in Agent Router. To admit or remove a whole population, adjust the IdP group or the rule; to cut off a single external identity after the fact, disable its provisioned principal. Your IdP stays the single source of truth for external-user lifecycle, which is also how the underlying Envoy Gateway JWT authentication is designed to work.

Persona: Platform operator or project administrator working in the Admin Dashboard, often in coordination with the identity team that owns the upstream provider.

Estimated time: 15 to 30 minutes for an initial configuration, depending on how quickly the IdP's issuer, audiences, and JWKS endpoint can be confirmed.

Outcomes

By the end of this guide:

One JWT identity provider is configured for the project and applies to all of its gateways.
Verified token claims resolve to an Agent Router principal, either a pre-registered one or one provisioned just in time within a capped project.
A request carrying a valid IdP token is accepted, and requests carrying forged or expired tokens are rejected.
Existing project API keys continue to work unchanged on the same gateways.

Prerequisites

Membership of the project, with permission to manage its gateway configuration.
The project already has a gateway provisioned, so there is an endpoint to authenticate against. See Provision a gateway for a project.
From the IdP, the values Agent Router validates every token against: the issuer (iss), the audiences (aud) the token carries, and either the JWKS URL where the public signing keys are published or the inline JWKS itself.
A way for your callers to place the IdP's token on a request header other than Authorization (the default is x-tars-idp-token).

Step 1: Open the Authentication tab

Use the project switcher at the top of the application to select the project the provider is for, for example bedrock-team.
Open the project and select the Authentication tab.
If no provider is configured yet, select Configure authentication. Otherwise, select Edit provider on the existing provider card.

Everything configured here applies to the currently selected project. Selecting the wrong project configures authentication for gateways you did not intend.

Step 2: Configure the JWT identity provider

Enter the provider's details and save it. Agent Router uses these to verify every incoming IdP token.

Give the provider a Name that is recognisable later, for example Okta production.
Set the Issuer to the iss value the IdP stamps on its tokens, for example https://okta.example.com/oauth2/default.
Choose a JWKS source. Select Remote URL and enter the endpoint where the IdP publishes its public signing keys, or select Inline JWKS and paste the key set directly. Remote keys are refreshed on a schedule.
Add the Audiences the token must carry, one per entry. A token whose aud does not include one of these values is rejected.
Leave the Extraction header as x-tars-idp-token unless your callers place the token elsewhere. It must not be Authorization, which is reserved for project API keys.
Set Enabled to on to begin verifying tokens as soon as the provider is saved, then save.

Once saved, the provider card shows the configuration and confirms it has been reconciled to every gateway in the project.

Provider field reference

Field	Description
Name	A label to recognise the provider across the dashboard. Does not affect verification.
Mechanism	The verification mechanism. `JWT` is the only mechanism in this phase.
Issuer	The `iss` claim every token is validated against.
JWKS source	Where Agent Router fetches the public signing keys: a remote URL (refreshed on a schedule) or an inline key set.
Audiences	The `aud` values a token must carry. A token missing all of them is rejected.
Extraction header	The request header the IdP token is read from. Defaults to `x-tars-idp-token`; must not be `Authorization`.
Enabled	Whether the provider verifies tokens. Turning it off stops accepting IdP tokens without deleting the configuration.

Step 3: Map verified claims to principals

A verified token is only accepted once a mapping rule resolves it to a principal, the identity that usage, budgets, and policy attach to. Rules are evaluated top-down and the first match wins, so order the more specific rules first.

On the provider, select Add rule.
Set the Claim name to the token claim to match on, for example email or groups.
Optionally set a Match template, a shell-style glob such as *@example.com. Leave it blank to match any value of the claim.
Choose a Target. Select Pre-registered to resolve to a principal that already exists, or JIT provision to create one on first sight.
For a JIT rule, choose the JIT project the new principal is created in and set a Principal cap, the maximum number of identities that project will auto-create before further new tokens are rejected.
Set the Principal type, then save the rule.

Repeat for each claim pattern you want to admit. A common shape is one JIT rule per trusted email domain or directory group, with a final pre-registered rule for known service identities.

Mapping-rule field reference

Field	Description
Claim name	The JWT claim the rule matches on, for example `sub`, `email`, or `groups`.
Match template	Optional shell-style glob the claim value must match. Blank matches any value.
Target	`Pre-registered` resolves to an existing principal; `JIT provision` creates one on first match.
JIT project	The project a just-in-time principal is created in. JIT rules only.
Principal cap	The maximum number of identities the JIT project auto-creates before new tokens are rejected. JIT rules only.
Principal type	The kind of principal the rule produces, for example an external identity or a service account.

Tokens are verified in full

A mapping rule runs only after the token itself is verified: its signature, issuer, audience, and expiry are checked against the configured JWKS. Claim headers a client sends are never trusted on their own, and the IdP token is never forwarded to an upstream model provider.

Step 4: Test and enable

Confirm the provider before relying on it.

From a client that holds a token from the IdP, send a request to the project's gateway with the token on the extraction header, for example:
```
curl https://<project-gateway-host>/v1/models \
  -H "x-tars-idp-token: <idp-jwt>"
```
Confirm the request is accepted and that its usage is attributed to the expected principal in the project's request logs.
Confirm a request carrying a forged, expired, or wrong-audience token is rejected, and that a request with the IdP token placed on Authorization is refused rather than treated as an API key.
Confirm an existing project API key still authenticates on the Authorization header, unchanged.

If verification is not behaving as expected, re-check the issuer, audiences, and JWKS source against the IdP, and confirm the token is on the extraction header rather than Authorization.

Configure with the admin API

The same provider and rules can be managed programmatically through the admin API, which is useful for configuration as code. The provider resource is created against the project:

curl https://<admin-api-host>/admin/v1/gateway-auth-policies \
  -H "X-API-Key: <admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "bedrock-team",
    "name": "Okta production",
    "mechanism": "jwt",
    "issuer": "https://okta.example.com/oauth2/default",
    "jwksUri": "https://okta.example.com/oauth2/default/v1/keys",
    "audiences": ["agent-router"],
    "extractionHeader": "x-tars-idp-token",
    "enabled": true
  }'

Mapping rules are then added to the returned policy, and the same operations are available through the Agent Router SDKs (gatewayAuthPolicy in the TypeScript and Python SDKs, GatewayAuthPolicy() in Go). See the SDK reference for language quickstarts.

What to do next

Issue a project-scoped API key: the other credential a gateway accepts, on the Authorization header, alongside IdP tokens. See Issue a project-scoped API key.
Configure single sign-on: the separate, organisation-wide identity flow for signing operators into the Admin Dashboard itself. See Configure single sign-on.

Where to go next

Issue a project-scoped API key

The API-key credential a gateway accepts alongside IdP tokens.

Configure single sign-on

Organisation-wide identity for signing operators into the dashboard.

How access control differs from project API keys​

Outcomes​

Prerequisites​

Step 1: Open the Authentication tab​

Step 2: Configure the JWT identity provider​

Provider field reference​

Step 3: Map verified claims to principals​

Mapping-rule field reference​

Step 4: Test and enable​

Configure with the admin API​

What to do next​