Connect a gateway changedclaude-tag/admins/federated-access/connect-a-gateway
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 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+12added
Lines−12removed
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> Gateways 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 **Gateways** section. Connecting a gateway needs an organization Owner, or an admin with full Claude Tag management permission.
1212
13A gateway is a service you run between Claude and your internal systems. Every request Claude sends it carries a signed identity token naming your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel). The gateway checks the token, decides what that agent may do, and forwards the request with your own credentials. No long-lived credential for your systems is stored in Claude.
13A gateway is a service you run between Claude and your internal systems. Every request Claude sends it carries a signed identity token naming your organization and the [agent](/docs/claude-tag/concepts/agent-identity.md) making the request (Claude's identity in one Slack channel). The gateway checks the token, decides what that agent may do, and forwards the request with your own credentials. No long-lived credential for your systems is stored in Claude.
1414
1515Two terms recur on this page. The **subject check** is what your gateway does to every token, confirming it belongs to your organization. The **connection check** is what the console does once, when you connect the gateway, confirming that your gateway performs the subject check.
1616
from line 38
3838| Control subject | A reserved test identity in your organization, copied from the dialog. Anthropic uses it only for the connection check. |
3939| Expiry | Tokens expire 10 minutes after they're issued. Check `exp`, allowing up to 60 seconds of clock skew. |
4040
41The subject check is yours to implement, and it's required, because every organization's tokens come from the same issuer; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). Implement the check in one of two forms, strongest first:
41The subject check is yours to implement, and it's 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). Implement the check in one of two forms, strongest first:
4242
4343* Accept only an explicit list of your own agents' full subjects, when your use case allows it. The sample gateway does this by default and offers the prefix form below as an opt-in setting. Agent IDs change when a Slack channel is deleted and recreated, so you update the list when that happens.
4444* Otherwise, reject every token whose `sub` doesn't start with your **Subject prefix**, or pin `iss` and `tenant` together. The `tenant` claim is your organization ID, the same value the subject carries between `/org/` and `/agent/`, so checking it is the subject check in claim form. This is the minimum.
from line 80
8080
8181Claude uses the gateway 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).
8282
83Claude also needs to know the gateway exists. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions):
83Claude also needs to know the gateway exists. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope.md#add-custom-instructions):
8484
8585```text wrap theme={null}
8686Internal APIs are behind https://gateway.example.com. Call GET /list-services there to see what is available.
from line 92
9292
9393## Verify the connection
9494
95[Federated connections](/docs/claude-tag/admins/federated-access/limits#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.
95[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.
9696
9797In a channel where the gateway's connection applies, start a new thread and ask Claude to make a small read through the gateway:
9898
from line 100
100100@Claude call GET /list-services on https://gateway.example.com and tell me what it returns.
101101```
102102
103If your gateway logs subjects and decisions, confirm the request arrived with a token that passed every check and a subject starting with your **Subject prefix**. [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) attaches the token at the network boundary; the model and the sandbox are not given it.
103If your gateway logs subjects and decisions, confirm the request arrived with a token that passed every check and a subject starting with your **Subject prefix**. [Agent Proxy](/docs/claude-tag/concepts/agent-identity.md#agent-proxy) attaches the token at the network boundary; the model and the sandbox are not given it.
104104
105105To disconnect a gateway, click **Remove** in the gateway's row of the **Gateways** table and confirm with **Remove gateway**. Claude stops using the gateway at once. A token issued before the removal stays valid until it expires, within 10 minutes.
106106
107107## Common errors
108108
109One message comes up while connecting. **"The check didn't pass"** means the gateway isn't reachable from the internet over HTTPS, its root route doesn't answer an empty `POST` directly, or the subject check is missing or rejects the **Control subject**. See [The check didn't pass](/docs/claude-tag/admins/federated-access/troubleshooting#the-check-didn%E2%80%99t-pass).
109One message comes up while connecting. **"The check didn't pass"** means the gateway isn't reachable from the internet over HTTPS, its root route doesn't answer an empty `POST` directly, or the subject check is missing or rejects the **Control subject**. See [The check didn't pass](/docs/claude-tag/admins/federated-access/troubleshooting.md#the-check-didn%E2%80%99t-pass).
110110
111111A bundle-step note that the gateway is already in a bundle isn't an error; the **Access bundle** list then offers the bundles it isn't in yet. To use the gateway in more channels without adding it to another bundle, apply a bundle it's in wherever you need the gateway; see [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab).
112112
113For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting).
113For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md).
114114
115If 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#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#how-scopes-inherit).
115If 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).
116116
117117## Related resources
118118
119* [Give Claude access](/docs/claude-tag/admins/add-connections): the bundle and connection model
120* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a gateway connection applies
121* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation
122* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
119* [Give Claude access](/docs/claude-tag/admins/add-connections.md): the bundle and connection model
120* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope.md): where a gateway connection applies
121* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference.md): every claim in the token, lifetimes, and key rotation
122* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md): console and runtime errors for every connection type
123123* [Sample gateway](https://github.com/anthropics/claude-tag-wif-gateway-sample): a reference gateway with offline tests
124124
No line in this hunk matches that.