Connect an authorization server changedclaude-tag/admins/federated-access/authorization-server
Nearest release: v2.1.290, published under an hour before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 5 Oct 2026 18:54 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+20added
Lines−20removed
From line
10
where the diff opens
First seen
10 Sep 2026
this site's first read of the page
Recorded edits11to this page, all time
The whole hunk
from line 10, old and new numbered
/
from line 10
1010>
1111> Authorization servers are connected on the [**Federated agent access**](https://claude.ai/admin-settings/claude-tag/federated-cloud-access) page, under **Claude Tag** in the admin settings sidebar. Use its **Authorization servers** section. Connecting a server needs an organization Owner, or an admin with full Claude Tag management permission.
1212
13With an authorization server connection, Claude presents a short-lived identity token to an OAuth 2.0 authorization server you run, receives one of your access tokens in return, and calls your APIs with it. No long-lived credential for your systems is stored in Claude, and [Agent Proxy](/docs/claude-tag/concepts/agent-identity.md#agent-proxy) holds each access token only until it expires. The identity token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity.md) making the request (Claude's identity in one Slack channel), and your server decides whether to issue a token for it.
13With an authorization server connection, Claude presents a short-lived identity token to an OAuth 2.0 authorization server you run, receives one of your access tokens in return, and calls your APIs with it. No long-lived credential for your systems is stored in Claude, and [Agent Proxy](https://claude.com/docs/claude-tag/concepts/agent-identity.md#agent-proxy) holds each access token only until it expires. The identity token names your organization and the [agent](https://claude.com/docs/claude-tag/concepts/agent-identity.md) making the request (Claude's identity in one Slack channel), and your server decides whether to issue a token for it.
1414
15Choose this when you run an authorization server that issues tokens for your APIs. If your own service will verify the identity token on every request instead, [connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway.md). If a vendor's API gave you a private key to sign assertions with (Salesforce, for example), use the [OAuth 2.0 JWT bearer](/docs/claude-tag/admins/connections/custom.md#oauth-2-0-jwt-bearer) credential type instead; the console labels this page's connection **Authorization server**.
15Choose this when you run an authorization server that issues tokens for your APIs. If your own service will verify the identity token on every request instead, [connect a gateway](https://claude.com/docs/claude-tag/admins/federated-access/connect-a-gateway.md). If a vendor's API gave you a private key to sign assertions with (Salesforce, for example), use the [OAuth 2.0 JWT bearer](https://claude.com/docs/claude-tag/admins/connections/custom.md#oauth-2-0-jwt-bearer) credential type instead; the console labels this page's connection **Authorization server**.
1616
1717Two terms recur on this page. The **subject check** is what your server does to every identity token, confirming it belongs to your organization. The **connection check** is the probe the console runs when a gateway is connected; it doesn't run for token endpoints.
1818
from line 26
2626 * isn't an IP address, a private-network name, an Anthropic-owned host, or a cloud token-exchange host
2727* The token endpoint is on a different host from the APIs Claude will call with the returned token, for example `auth.example.com` and `api.example.com`, or its address has a folder of its own, like `/oauth2` in `https://auth.example.com/oauth2/token`.
2828* Your server can reach `https://identity.anthropic.com` to fetch Anthropic's signing keys.
29* An organization can register up to 5 [gateways](/docs/claude-tag/admins/federated-access/connect-a-gateway.md), and an authorization server's audience address (its **Issuer URL** value, or its token endpoint when that field is empty) counts as one.
29* An organization can register up to 5 [gateways](https://claude.com/docs/claude-tag/admins/federated-access/connect-a-gateway.md), and an authorization server's audience address (its **Issuer URL** value, or its token endpoint when that field is empty) counts as one.
3030
3131## Copy the values from the console
3232
from line 37
3737| Issuer | `https://identity.anthropic.com/agents`, matched exactly. The OpenID Connect (OIDC) discovery document is at `https://identity.anthropic.com/agents/.well-known/openid-configuration`. |
3838| JWKS URL | The JSON Web Key Set (JWKS) named by `jwks_uri` in the discovery document, `https://identity.anthropic.com/agents/jwks.json`. Accept ES256 only. Select the key by `kid`, and refetch the JWKS on an unknown `kid` before rejecting the token. |
3939| Audience | Your authorization server's issuer identifier, as you enter it in the **Issuer URL** field when you connect the server, for example `https://auth.example.com`. It must be an HTTPS URL on the same host as the token endpoint. If your server requires the token endpoint URL as the audience instead, leave **Issuer URL** empty and the audience is the token endpoint address as the console stores it (the host lowercased, a bare trailing slash dropped, the rest kept as entered). Either way, copy the **Audience** row into your verifier rather than typing it. The `aud` claim is a JSON array with one element. Accept only this exact value, not any address on your host. |
40| Subject prefix | `wimse://identity.anthropic.com/org/<your organization ID>/agent/`. Every token's `sub` claim starts with this prefix and ends with one agent's ID; see the [subject](/docs/claude-tag/admins/federated-access/token-reference.md#subject) format. Agent IDs aren't shown in the console; your server learns them from the tokens it receives, and they change, for example when a Slack channel is deleted and recreated. |
40| Subject prefix | `wimse://identity.anthropic.com/org/<your organization ID>/agent/`. Every token's `sub` claim starts with this prefix and ends with one agent's ID; see the [subject](https://claude.com/docs/claude-tag/admins/federated-access/token-reference.md#subject) format. Agent IDs aren't shown in the console; your server learns them from the tokens it receives, and they change, for example when a Slack channel is deleted and recreated. |
4141| Tenant | Your organization ID, the value between `/org/` and `/agent/` in the **Subject prefix**, carried in every token as the `tenant` claim. |
4242| Expiry | Tokens expire 10 minutes after they're issued. Check `exp`, allowing up to 60 seconds of clock skew. |
4343
from line 54
5454Your server must:
5555
5656* Verify the token with a standard JWT or OIDC library configured with the issuer, JWKS URL, audience, and expiry from [Copy the values from the console](#copy-the-values-from-the-console).
57* Check the subject. Where your use case allows, accept only the full subjects of your own agents, and update that list when a Slack channel is deleted and recreated. At minimum, reject every token whose `sub` doesn't start with your **Subject prefix**, or equivalently pin `iss` and reject every token whose `tenant` isn't your organization ID. This check is required because every organization's tokens come from the same issuer; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference.md#authorize-on-the-subject). The console's connection check doesn't run for token endpoints, so nothing tests this check for you.
57* Check the subject. Where your use case allows, accept only the full subjects of your own agents, and update that list when a Slack channel is deleted and recreated. At minimum, reject every token whose `sub` doesn't start with your **Subject prefix**, or equivalently pin `iss` and reject every token whose `tenant` isn't your organization ID. This check is required because every organization's tokens come from the same issuer; see [Authorize on the subject](https://claude.com/docs/claude-tag/admins/federated-access/token-reference.md#authorize-on-the-subject). The console's connection check doesn't run for token endpoints, so nothing tests this check for you.
5858* Decide what the agent may do, for example from the agent ID at the end of `sub`, and issue an access token for it. Tokens may carry additional opaque claims; ignore claims you don't recognize.
5959* Return `200` with a JSON body: `access_token`, `token_type` (`Bearer`, compared without regard to case, and may be omitted), and `expires_in` in seconds.
6060
from line 84
8484
8585Optionally enter a **Resource**, the API the returned token should be scoped to as an absolute URI (for example `https://api.example.com`), and a **Scope**, space-separated scopes to request. In **Allowed API hosts**, add the hosts Claude may call with the returned token, for example `api.example.com`. A wildcard as the leftmost label matches any subdomain. An entry or wildcard can cover the token endpoint's host only when the endpoint's address has a folder of its own, like `/oauth2` in `https://auth.example.com/oauth2/token`. In that case, list the paths Claude may use, such as `/graphql`, under **Allowed API paths**. A listed path covers everything under it, and a path that overlaps the token endpoint's folder isn't allowed. Then choose a bundle from the **Access bundle** list (or create one: click **New bundle** if the dialog shows it, enter a **Bundle name**, and click **Create bundle**) and click **Connect server**.
8686
87This creates a [connection](/docs/claude-tag/admins/add-connections.md) in that bundle, with the API hosts under **Allowed hosts**. Agent Proxy attaches the access token as an `Authorization: Bearer` header to every request Claude makes to those hosts. A token endpoint can be connected once in your organization, in one bundle, and the connection applies wherever that bundle applies.
87This creates a [connection](https://claude.com/docs/claude-tag/admins/add-connections.md) in that bundle, with the API hosts under **Allowed hosts**. Agent Proxy attaches the access token as an `Authorization: Bearer` header to every request Claude makes to those hosts. A token endpoint can be connected once in your organization, in one bundle, and the connection applies wherever that bundle applies.
8888
8989The **Authorization servers** table lists each server by its **Token endpoint**, with its **Access bundle**, its **Allowed hosts**, when it was **Added**, and a **Remove** action. The audience address also appears in the **Gateways** table with its check marked **Skipped** and a note that a connected authorization server uses it.
9090
9191## Let agents use the APIs
9292
93Claude uses the connection in the channels where its bundle applies. A bundle you created in the connect dialog applies nowhere until you choose places; see [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab).
93Claude uses the connection in the channels where its bundle applies. A bundle you created in the connect dialog applies nowhere until you choose places; see [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab).
9494
95Claude also needs to know what the APIs are for. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope.md#add-custom-instructions):
95Claude also needs to know what the APIs are for. Add a line like this to the scope's [custom instructions](https://claude.com/docs/claude-tag/admins/attach-to-scope.md#add-custom-instructions):
9696
9797```text wrap theme={null}
9898The internal orders API is at https://api.example.com; see GET /openapi.json for what it offers. Authentication is already set up.
from line 100
100100
101101The exchange happens in Agent Proxy, outside Claude's sandbox, so neither the identity token nor your access token is visible to Claude, and Claude can't perform the exchange itself.
102102
103New threads pick up the connection on their own. In a thread already running, ask Claude to use the API and name its host. If Claude still can't, send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) in that thread. Claude then continues from a fresh session with your organization's current configuration.
103New threads pick up the connection on their own. In a thread already running, ask Claude to use the API and name its host. If Claude still can't, send [`@Claude !restart`](https://claude.com/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) in that thread. Claude then continues from a fresh session with your organization's current configuration.
104104
105105## Verify the connection
106106
107[Federated connections](/docs/claude-tag/admins/federated-access/limits.md#where-federated-connections-work) work only in agent sessions, such as a Slack channel. A test from a personal session, such as a direct message with `@Claude`, won't work.
107[Federated connections](https://claude.com/docs/claude-tag/admins/federated-access/limits.md#where-federated-connections-work) work only in agent sessions, such as a Slack channel. A test from a personal session, such as a direct message with `@Claude`, won't work.
108108
109109In a channel where the connection applies, start a new thread and ask Claude to make a small read:
110110
from line 112
112112@Claude call GET /openapi.json on https://api.example.com and tell me what the API offers.
113113```
114114
115Then check your authorization server's logs for a JWT bearer grant whose token has your **Subject prefix**, and your API's logs for a request carrying the access token it issued. If the grant was refused, your server's own error is the reason; Claude sees only that the request failed. See [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md) for the errors Claude shows.
115Then check your authorization server's logs for a JWT bearer grant whose token has your **Subject prefix**, and your API's logs for a request carrying the access token it issued. If the grant was refused, your server's own error is the reason; Claude sees only that the request failed. See [Troubleshoot federated agent access](https://claude.com/docs/claude-tag/admins/federated-access/troubleshooting.md) for the errors Claude shows.
116116
117117## Remove the server
118118
from line 123
123123Five messages come up while connecting:
124124
125125* **"The issuer URL must be an https URL on the same host as the token endpoint. Leave it empty to use the token endpoint as the audience."**: the **Issuer URL** value is not an HTTPS URL on the token endpoint's host. Enter the issuer identifier your server uses there, or clear the field.
126* **"This token endpoint is already connected in the bundle"**: the server already has its one connection. Apply that bundle where you need the server instead; see [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab).
126* **"This token endpoint is already connected in the bundle"**: the server already has its one connection. Apply that bundle where you need the server instead; see [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab).
127127* **"This organization has reached its limit of 5 registered gateways, which includes token endpoints"**: remove an unused row from the **Gateways** table first.
128128* **"The allowed hosts can't include the token endpoint's host"**: an **Allowed API hosts** entry, or a wildcard in it, covers the token endpoint's host, and the endpoint's address has no folder of its own. Put the token endpoint on a different host from the APIs, or use a token endpoint address with a folder of its own, like `/oauth2` in `https://auth.example.com/oauth2/token`.
129* **"That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first."**: the token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your bundles. Enter the server's own addresses, or delete that gateway's connection from its bundle first, as [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes.
129* **"That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first."**: the token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your bundles. Enter the server's own addresses, or delete that gateway's connection from its bundle first, as [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes.
130130
131For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md).
131For other dialog messages, see [Troubleshoot federated agent access](https://claude.com/docs/claude-tag/admins/federated-access/troubleshooting.md).
132132
133If Claude reports HTTP 403 with a reason that starts with [`request blocked: federated connections work only in agent sessions (such as a Slack channel), not in personal sessions (such as a direct message)`](/docs/claude-tag/admins/federated-access/troubleshooting#request-blocked-federated-connections-work-only-in-agent-sessions-such-as-a-slack-channel--not-in-personal-sessions-such-as-a-direct-message), the request came from a personal session, such as a direct message with `@Claude`. A personal session runs under a person's own account. [Federated connections](/docs/claude-tag/admins/federated-access/limits.md#where-federated-connections-work) work only in agent sessions, so test again from a new thread in a Slack channel where the connection [applies](/docs/claude-tag/admins/attach-to-scope.md#how-scopes-inherit).
133If Claude reports HTTP 403 with a reason that starts with [`request blocked: federated connections work only in agent sessions (such as a Slack channel), not in personal sessions (such as a direct message)`](https://claude.com/docs/claude-tag/admins/federated-access/troubleshooting#request-blocked-federated-connections-work-only-in-agent-sessions-such-as-a-slack-channel--not-in-personal-sessions-such-as-a-direct-message), the request came from a personal session, such as a direct message with `@Claude`. A personal session runs under a person's own account. [Federated connections](https://claude.com/docs/claude-tag/admins/federated-access/limits.md#where-federated-connections-work) work only in agent sessions, so test again from a new thread in a Slack channel where the connection [applies](https://claude.com/docs/claude-tag/admins/attach-to-scope.md#how-scopes-inherit).
134134
135135## Related resources
136136
137* [Give Claude access](/docs/claude-tag/admins/add-connections.md): the bundle and connection model
138* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope.md): where a connection applies
139* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference.md): every claim in the token, lifetimes, and key rotation
140* [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway.md): the alternative where your own service verifies the token on every request
141* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md): console and runtime errors for every connection type
137* [Give Claude access](https://claude.com/docs/claude-tag/admins/add-connections.md): the bundle and connection model
138* [Attach a bundle to a scope](https://claude.com/docs/claude-tag/admins/attach-to-scope.md): where a connection applies
139* [Identity token reference](https://claude.com/docs/claude-tag/admins/federated-access/token-reference.md): every claim in the token, lifetimes, and key rotation
140* [Connect a gateway](https://claude.com/docs/claude-tag/admins/federated-access/connect-a-gateway.md): the alternative where your own service verifies the token on every request
141* [Troubleshoot federated agent access](https://claude.com/docs/claude-tag/admins/federated-access/troubleshooting.md): console and runtime errors for every connection type
142142
No line in this hunk matches that.