One read of Claude Documentationclaude-docs-20260930T193709Z
11 pages moved out of 258 read.
Pages moved
11
significant first
Pages read
258
in this capture
Captured
19:37 UTC
Corpus hash
9ff03914b360
corpus-hash
What this read moved
1-11 of 11claude-science/command-line-settings Changed · +47 / -15 lines
### Roll back to an earlier build
from line 1
11# Command line settings
22
3> Reference for the claude-science command: every subcommand, the serve flags, the single-use login link, and the environment variables Claude Science reads.
3> Reference for the claude-science command: its subcommands, the serve flags, the single-use login link, and the environment variables you can set.
44
5Reference for the claude-science command: every subcommand, the serve flags, the single-use login link, and the environment variables Claude Science reads.\
6claude-science serve starts Claude Science and opens the web app in your browser at a single-use login link. Everyday use is that one command. The others manage the running program: they mint login links, report status, follow logs, install updates, and merge data directories. On Windows, the installer adds the command to your PATH for new terminals. There the app window you open from the Start menu is the everyday way in, and the commands below manage the same running program.
5Reference for the claude-science command: its subcommands, the serve flags, the single-use login link, and the environment variables you can set.\
6claude-science serve starts Claude Science and opens the web app in your browser at a single-use login link. On Linux, everyday use is that one command. The others manage the running program: they mint login links, report status, follow logs, install updates, and merge data directories. On Windows, the installer adds the command to your PATH for new terminals. There the app window you open from the Start menu is the everyday way in, and the commands below manage the same running program.
77
88## Commands
99
from line 11
1111| - | - |
1212| `claude-science serve` | Start the background program and open the web app in your browser at a single-use login link. One runs per data directory; Ctrl-C stops it. |
1313| `claude-science open` | Mint a fresh login link from the running program and open it in your browser. |
14| `claude-science url` | Print a fresh login link alone on standard output and nothing else. |
14| `claude-science url` | Print a fresh login link. At a terminal, the link comes inside a short banner. When you pipe or capture the output, standard output carries only the link. |
1515| `claude-science status` | Print whether the program is running, the version, and the port, as JSON. |
1616| `claude-science logs` | Print the newest log file from the data directory. `--tail` follows it live. |
1717| `claude-science stop` | Stop the program cleanly. |
18| `claude-science update` | Check for and install an update. `--check` only reports; --to `<version>` installs a specific version, which is also how you roll back. Updates are signature-verified and replace the binary atomically. |
18| `claude-science update` | Check for and install an update. `--check` only reports; `--to <build>` installs a specific build, which is also how you roll back (see [Roll back to an earlier build](#roll-back-to-an-earlier-build)). Updates are signature-verified and replace the binary atomically. |
1919| `claude-science import` `<path>` | Merge another data directory, or its database file, into this one. |
20| `claude-science install` | Windows only. Install the app for your user account, with a PATH entry, a Start menu shortcut, and an uninstall entry under Windows **Settings > Apps > Installed apps**. Run it again to repair them. |
2021| `claude-science uninstall` | Windows only. Remove the app, its shortcuts, and its PATH entry while keeping your data; `--purge` also deletes the data directory. Quit Claude Science first. |
2122| `claude-science --version` | Print the version. |
22| `claude-science` `<command>` --help | Print help for any command. |
23| `claude-science <command> --help` | Print help for any command. |
2324
2425<Note>
2526 `import` has no preview and no undo. Back up the data directory before you run it; running the same import a second time is safe.
2627</Note>
2728
29### Roll back to an earlier build
30
31`claude-science update --to <build>` installs one specific build. `<build>` is an 8-character build ID such as `3f9a01bc`, not a version number. `claude-science update --check` prints the ID of the installed build as `Current`.
32
33Claude Science checks for updates in the background and shows **Update available** when one is ready. Note the `Current` ID before you choose **Restart to update**, so you know which build to go back to.
34
35If a newer build has already changed how your data directory stores sessions, the command refuses an older build and installs nothing, because an older build can permanently lose part of every session it writes to. The refusal names a flag that overrides it, `--accept-layout-downgrade`, and says when that is safe. If you cannot tell from the message whether it is safe for you, do not add the flag.
36
37<Note>
38 An older build that does install can still refuse to start if a newer build has already updated the database in your data directory. When it does, it stops at startup and changes nothing in your data. At a terminal, it says the data was `written by a NEWER version`. To start the app again, run `claude-science update`, which installs the latest build.
39</Note>
40
2841## Global flags
2942
3043These two work on every command. On Windows, `~` in the defaults below is your user profile folder, `%USERPROFILE%`.
from line 44
3144
3245| Flag | Default | What it does |
3346| - | - | - |
34| `--data-dir` `<dir>` | `~/.claude-science` | The data directory to use. |
47| `--data-dir` `<dir>` | `~/.claude-science` | The data directory to use. Sign-in tokens and the shared package environment stay under `~/.claude-science` whichever directory you choose, so all your data directories share one sign-in. |
3548| `--config` `<file>` | `~/.claude-science/config.toml` | The configuration file to read. |
3649
3750## The login link
3851
39When serve starts, it prints a line of the form `Web UI -> http://localhost:<port>/?nonce=...`. The nonce is a one-time password: it signs one browser tab in and then expires, about three minutes after it is printed. The signed-in tab stays signed in until you restart the program.\
40You never need to keep a link. claude-science open mints a fresh one and opens it in your browser whenever you want to sign in again. For a machine you reach over SSH, claude-science url prints a fresh link alone on standard output: run it there, then open the printed link through your tunnel. The app listens on 127.0.0.1 unless you change --host, so it is reachable only from your own machine.
52When serve starts, it prints a line of the form `Web UI → http://localhost:<port>/?nonce=...`. The nonce is a one-time password: it signs one browser tab in and then expires, about three minutes after it is printed. The signed-in tab stays signed in until you restart the program.\
53You never need to keep a link. claude-science open mints a fresh one and opens it in your browser whenever you want to sign in again.
4154
55The app listens on 127.0.0.1 unless you change `--host`, so it is reachable only from the machine it runs on. For a machine you reach over SSH, first forward two ports from your computer, the web app port and the preview port (by default the web app port plus one), as [Run on a remote Linux server](/docs/claude-science/run-on-remote-linux-server#forward-the-ports-from-your-computer) shows. Then run claude-science url on that machine and open the link it prints in your own browser.
56
4257## Flags for serve
4358
4459| Flag | Default | What it does |
4560| - | - | - |
46| `--port` `<n>` | `8000` | The port the web app is served on. 0 picks a free port. |
61| `--port` `<n>` | `8000` | The port the web app is served on. 0 picks a free port. If you did not pass `--port` and 8000 is busy, the app takes the next free port and says so. If you passed `--port` and that port is busy, serve exits and tells you to pick a different one. `claude-science status` prints the port in use. |
4762| `--no-browser` | off | Do not open a browser. url prints a login link any time you want one. |
48| `--detached` | off | Run in the background. Implies --no-browser. |
63| `--detached` | off | Run in the background. Implies `--no-browser`. |
4964| `--no-auto-update` | off | Do not check for or install updates. For a pinned or centrally managed install. |
50| `--host` `<address>` | 127.0.0.1 | The address the app listens on. Anything else exposes the app to your network; prefer an SSH tunnel. |
65| `--host` `<address>` | 127.0.0.1 | The address the app listens on. Any other address exposes the app to your network. To work from another machine, use an SSH tunnel. |
5166| `--base-path` `</prefix>` | unset | Serve the app under a URL prefix behind a reverse proxy. |
52| `--allow-origin` `<url>` | unset | An extra browser Origin allowed to connect; repeat the flag for more than one. It does not change which sites Claude can reach. |
67| `--allow-origin` `<url>` | unset | An extra browser Origin allowed to connect, written as `https://<host>` with an optional port and no path. A value that starts with `http://`, has a path, or has no `https://` in front is ignored without a message. Repeat the flag for more than one. It does not change which sites Claude can reach. |
5368| `--sandbox-port` `<n>` | port + 1 | The separate origin that previews of generated HTML are served from, so a previewed page cannot read your session. |
5469| `--verbose` | off | Show startup and info log lines on the console; by default they go only to the log file. |
5570
5671## Dangerous flags
5772
73`claude-science serve` accepts two flags that each turn off a protection.
74
5875<Warning>
59 `--dangerously-no-sandbox` runs code with full read and write access to your home directory and an unrestricted network. `--dangerously-skip-approvals` approves every permission card automatically, for everything, until you restart without the flag; questions addressed to you still appear. Neither belongs in everyday use.
76 * `--dangerously-no-sandbox` turns the [sandbox](/docs/claude-science/core-concepts#sandbox) off. On macOS and Linux, the code Claude runs then has full read and write access to your home directory and unrestricted network access. On Windows, code cells do not run at all while the flag is set.
77 * `--dangerously-skip-approvals` approves [permission cards](/docs/claude-science/core-concepts#permission-cards) for you without showing them, until you restart without the flag. That includes Claude's requests to run code, reach network hosts, open folders, and use connector tools. Cards still show for a connector tool you set to [**Ask each time**](/docs/claude-science/custom-connectors) and for requests only you can answer, such as entering an SSH password, permanently deleting artifacts, or spending usage credits. Questions Claude asks you still appear.
78
79 These flags are acceptable only on a machine that is already isolated, such as a container or a disposable virtual machine. Never use them with data or prompts that came from someone else, because Claude may follow instructions hidden in them. Neither belongs in everyday use.
6080</Warning>
6181
82If your organization [manages the network allowlist](/docs/claude-science/admin-controls#network-allowlist), the app ignores `--dangerously-no-sandbox` and keeps the sandbox on. If the app learns of that setting only after it has started without the sandbox, it pauses new sessions and messages until you restart it.
83
6284## Environment variables
6385
64`DO_NOT_TRACK`, set to any value other than `0` or `false`, turns usage analytics and error reports off. It is the same switch as `disable_telemetry = true` in the configuration file. `GITHUB_TOKEN` is optional and is used only against `api.github.com`, to lift the rate limit when you install a skill from a GitHub repository. Claude Science also reads the standard proxy variables (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, and `ALL_PROXY`); see [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks#connect-through-an-outbound-proxy). The proxy address variables are the one case where the environment overrides the configuration file, and `NO_PROXY` is merged with the `no_proxy` key rather than replacing it. Every other setting belongs in the configuration file.
86`DO_NOT_TRACK`, set to any value other than `0` or `false`, turns usage analytics and error reports off. It is the same switch as `disable_telemetry = true` in the configuration file. `GITHUB_TOKEN` (or `GH_TOKEN`) is optional and is used only against `api.github.com`, to lift the rate limit when you install a skill from a GitHub repository. Claude Science also reads the standard proxy variables (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, and `ALL_PROXY`); see [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks#connect-through-an-outbound-proxy). The proxy address variables are the one case where the environment overrides the configuration file, and `NO_PROXY` is merged with the `no_proxy` key rather than replacing it. Every other setting belongs in the configuration file.
6587
88An app started from the macOS Dock or Finder, or from the Windows Start menu, does not see variables exported in a terminal. The macOS app reads the `env` file in the data directory (by default `~/.claude-science/env`) when it starts, so put the variable there as a `KEY=VALUE` line, then quit and reopen the app. On Windows, set it as a user environment variable, then quit and reopen the app. See [How the environment variables reach the app](/docs/claude-science/corporate-networks#how-the-environment-variables-reach-the-app).
89
6690## See also
6791
6892<CardGroup cols={1}>
93 <Card title="Run on a remote Linux server" href="/docs/claude-science/run-on-remote-linux-server">
94 Install Claude Science on a server and use it from your own browser through an SSH tunnel.
95 </Card>
96
97 <Card title="Configuration file reference" href="/docs/claude-science/configuration-file-reference">
98 Find the `config.toml` file and set its network-related keys.
99 </Card>
100
69101 <Card title="Remote compute clusters" href="/docs/claude-science/remote-compute-clusters">
70102 Connect an SSH host and run jobs on it.
71103 </Card>
claude-science/run-on-remote-linux-server Changed · +7 / -5 lines
from line 21
2121```
2222
2323<Note>
24 The sandbox requires bubblewrap 0.8.0 or later; check with `bwrap --version`. Ubuntu 24.04 ships a new enough version, and Ubuntu 22.04 doesn't. The sandbox isn't optional: Claude Science refuses to start rather than run code unsandboxed.
24 The sandbox requires bubblewrap 0.8.0 or later; check with `bwrap --version`. Ubuntu 24.04 ships a new enough version, and Ubuntu 22.04 doesn't. If Claude Science can't set up the sandbox, it refuses to start rather than run code unsandboxed.
2525</Note>
2626
2727## Run Claude Science without administrator access
from line 59
5959
6060Set up the tunnel before you start Claude Science: the sign-in link it prints is only valid for about three minutes.
6161
62By default, the web app listens only on the server's localhost, so it isn't exposed to the network. An SSH tunnel makes it reachable from your computer. Claude Science uses two ports: one for the web app (8000) and a separate one for previews of generated HTML, served from its own origin so a previewed page can't read your session. The preview port is always the web app port plus one, so 8001 by default. Forward both. In a terminal on your computer:
62By default, the web app listens only on the server's localhost, so it isn't exposed to the network. An SSH tunnel makes it reachable from your computer. Claude Science uses two ports: one for the web app (8000) and a separate one for previews of generated HTML, served from its own origin so a previewed page can't read your session. The preview port defaults to the web app port plus one, so 8001. Forward both. In a terminal on your computer:
6363
6464```bash theme={null}
from line 67
6767
6868Leave that terminal open; the tunnel lasts as long as the SSH connection. If you work on the server through VS Code's Remote-SSH extension, it forwards ports automatically as the app uses them; check its Ports panel to confirm both ports are forwarded.
6969
70If the preview port is taken on the server, Claude Science uses a free port instead. After you start it, `claude-science url` prints both ports. Add a forward for the preview port it prints, with that number on both sides (`-L <port>:localhost:<port>`).
71
7072## Start Claude Science
7173
7274On the server:
from line 77
7577claude-science serve --no-browser
7678```
7779
78First launch prints the sign-in link, of the form `http://localhost:8000/?nonce=...`, right away, and continues setting up its starter Python and R environments; the setup can take a few minutes and about 5 GB of disk. If port 8000 or 8001 is taken on either machine, pass a different port to serve (for example `--port 8765`; previews then use the next port up, 8766) and change the `ssh -L` forwards to match.
80First launch prints the sign-in link, of the form `http://localhost:8000/?nonce=...`, right away, and continues setting up its starter Python and R environments; the setup can take a few minutes and about 5 GB of disk. If port 8000 or 8001 is taken on either machine, pass a different port to serve (for example `--port 8765`) and change the `ssh -L` forwards to match. Previews then use the next port up, 8766, if it is free.
7981
8082To run it in the background instead, use `claude-science serve --no-browser --detached`. `claude-science status` reports whether it's running, and `claude-science stop` stops it.
8183
from line 89
8789
8890## Keep it up to date
8991
90`claude-science update` checks for and installs updates. See [Command line settings](/docs/claude-science/command-line-settings) for the full command reference, including `logs` and the `serve` flags.
92`claude-science update` checks for and installs updates. See [Command line settings](/docs/claude-science/command-line-settings) for the command reference, including `logs` and the `serve` flags.
9193
9294## Troubleshooting
9395
from line 106
104106| A message mentioning `daemon already running on port 8000` | Claude Science is already running. Run `claude-science url` for a fresh sign-in link, or `claude-science stop` to stop it. |
105107| The sign-in link shows an expired-link page | Links are single-use and valid for about three minutes. Run `claude-science url` on the server and open the fresh link; restarting with `claude-science stop` then `claude-science serve --no-browser` also prints one. |
106108| Sign-in stops at claude.ai | The redirect couldn't return through the tunnel (choose **Paste code instead**), your account is on the Free plan (an upgrade is required), or your Team or Enterprise organization hasn't [enabled Claude Science](/docs/claude-science/enable-claude-science) yet. |
107| Interactive HTML previews render as static snapshots after a short delay (charts don't respond) | The tunnel isn't forwarding the preview port. Add the second `-L` forward; the preview port is the web app port plus one (8001 by default). |
109| Interactive HTML previews render as static snapshots after a short delay (charts don't respond) | The tunnel isn't forwarding the preview port. Add the second `-L` forward for the preview port that `claude-science url` prints (8001 by default), with that number on both sides. |
108110| The browser can't reach `localhost:8000` | The tunnel isn't up; rerun the `ssh -L` command. If the tunnel is up, confirm Claude Science is running on the server with `claude-science status`. |
109111| The installer reports no binary for your platform | Claude Science on Linux needs x64 with glibc. arm64 servers and musl-based distributions such as Alpine aren't supported. |
110112
claude-tag/admins/federated-access/authorization-server Changed · +5 / -5 lines
from line 6
66
77<BetaNote />
88
9<Note>Authorization servers are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Authorization servers** section. Connecting a server needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
9<Note>Authorization servers are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated agent access** in the left navigation and use the **Authorization servers** section. Connecting a server needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
1010
1111With 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#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) making the request (Claude's identity in one Slack channel), and your server decides whether to issue a token for it.
1212
from line 28
2828
2929## Copy the values from the console
3030
31In **Authorization servers**, click **Connect an authorization server**, enter your token endpoint in the **Token endpoint** field, enter your authorization server's issuer identifier in the **Issuer URL** field (or leave it empty if your server requires the token endpoint URL as the audience), and copy the **Issuer**, **JWKS URL**, **Audience**, and **Subject prefix** rows from the **Set your authorization server to accept these values** card. Then click **Cancel**; you register the endpoint after configuring the server.
31In **Authorization servers**, click **Connect an authorization server**, enter your token endpoint in the **Token endpoint** field, enter your authorization server's issuer identifier in the **Issuer URL** field (or leave it empty if your server requires the token endpoint URL as the audience), and copy the **Issuer**, **JWKS URL**, **Audience**, and **Subject prefix** rows from the **Set your authorization server to accept these values** card. The card also has a **Tenant ID for tokens** row, your organization ID, which the token carries in its `tenant` claim. Then click **Cancel**; you register the endpoint after configuring the server.
3232
3333| Value | What to configure |
3434| :- | :- |
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 cloud access](/docs/claude-tag/admins/federated-access/troubleshooting) 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](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows.
116116
117117## Remove the server
118118
from line 128
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. Put the token endpoint on a different host from the APIs.
129129* **"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 Access bundles. Enter the server's own addresses, or delete that gateway's connection from its bundle first.
130130
131For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting).
131For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting).
132132
133133If 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 under the [scope](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit) of the Access bundle that holds the connection.
134134
from line 138
138138* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a connection applies
139139* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation
140140* [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway): the alternative where your own service verifies the token on every request
141* [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
141* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
142142
claude-tag/admins/federated-access/aws Changed · +5 / -5 lines
from line 6
66
77<BetaNote />
88
9<Note>AWS roles are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Cloud roles** section. Connecting a role needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
9<Note>AWS roles are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated agent access** in the left navigation and use the **Cloud roles** section. Connecting a role needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
1010
1111With an AWS role connection, Claude signs in to an IAM role in your AWS account with a short-lived identity token and calls AWS with the role's permissions. No access key is stored in Claude. The token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel), and your role's trust policy decides which tokens to accept. If someone else manages your AWS account, give them the values from the console and the trust policy below; the console steps need a Claude Tag admin.
1212
from line 18
1818
1919## Copy the values from the console
2020
21In **Cloud roles**, click **Connect an AWS role** and copy the **Issuer**, **Audience**, and **Subject prefix** rows from the **Set the role's trust policy to accept these values** card. Then click **Cancel**; you connect the role after creating it in AWS.
21In **Cloud roles**, click **Connect an AWS role** and copy the **Issuer**, **Audience**, and **Subject prefix** rows from the **Set the role's trust policy to accept these values** card. The card also has a **Tenant ID for tokens** row with your organization ID, and a **StringLike sub** row with your **Subject prefix** plus `*`, the value the trust policy's `StringLike` condition takes. Then click **Cancel**; you connect the role after creating it in AWS.
2222
2323| Value | What it is |
2424| :- | :- |
from line 134
134134* `AccessDenied` on the sign-in means the trust policy didn't accept the token. Check the `sub` condition and the condition-key prefix.
135135* A denied action after a successful sign-in means AWS denied the action. Check the role's permissions policy first, then any bucket policy, permissions boundary, or service control policy.
136136
137See [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows.
137See [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows.
138138
139139To disconnect a role, click **Remove** in the role's row of the **Cloud roles** table, then **Remove role** in the confirmation. Claude stops using the role within about a minute, in existing threads as well as new ones, and the connection is removed from its bundle. Credentials from an earlier sign-in stay valid in AWS until they expire, within 1 hour; they're held only by Agent Proxy, never by Claude's sandbox.
140140
from line 145
145145* **"This role is already connected in the bundle"**: the role already has its one connection. [Attach that bundle to the scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead.
146146* **"Enter a role ARN like `arn:aws:iam::123456789012:role/ClaudeTag`"**: the **Role ARN** field rejected the value, most often because the ARN is in the AWS GovCloud (US) or AWS China partition, which can't be connected.
147147
148For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting).
148For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting).
149149
150150If 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 under the [scope](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit) of the Access bundle that holds the connection.
151151
from line 154
154154* [Give Claude access](/docs/claude-tag/admins/add-connections): the Access bundle and connection model
155155* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a role connection applies
156156* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation
157* [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
157* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
158158* [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom#aws-sigv4): the stored-key alternative, and how Claude signs AWS requests
159159
claude-tag/admins/federated-access/connect-a-gateway Changed · +10 / -11 lines
from line 6
66
77<BetaNote />
88
9<Note>Gateways are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Gateways** section. Connecting a gateway needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
9<Note>Gateways are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated agent access** in the left navigation and use the **Gateways** section. Connecting a gateway needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
1010
1111A 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.
1212
from line 22
2222
2323## Copy the values and deploy the gateway
2424
25In **Gateways**, click **Connect a gateway** and copy the **Issuer**, **JWKS URL**, **Subject prefix**, and **Control subject** rows from the **Set your gateway to accept these values** card, which appears as soon as the dialog opens and doesn't depend on the address. Then click **Cancel**; you register the gateway after deploying it.
25In **Gateways**, click **Connect a gateway** and copy the **Issuer**, **JWKS URL**, **Subject prefix**, and **Control subject** rows from the **Set your gateway to accept these values** card, which appears as soon as the dialog opens and doesn't depend on the address. The card also has a **Tenant ID for tokens** row, your organization ID, which the token carries in its `tenant` claim. Then click **Cancel**; you register the gateway after deploying it.
2626
2727Claude authenticates with a JSON Web Token (JWT) in the `Authorization: Bearer` header of every request. It reuses one token for a session's requests for about five minutes, or until your gateway answers 401, and then requests a new one, so don't treat a repeated `jti` as a replay. Verify it with a standard JWT or OpenID Connect (OIDC) library configured with these values.
2828
from line 66
6666 </Step>
6767
6868 <Step title="Run the connection check">
69 Leave the **Run the check** option selected and click **Run check and connect**. The check can take up to a minute. If it fails, nothing is registered; see [Common errors](#common-errors). If the gateway can't be reached from the internet yet, select the **Skip the check** option, enter a **Reason for skipping**, and click **Connect without the check**. The reason is shown in the **Gateways** table. Entering an address that is already registered runs the check again (unless you skip it) without changing the stored result, then moves to the bundle step.
69 Leave the **Run the check** option selected and click **Run check and connect**. The check can take up to a minute. If it fails, nothing is registered; see [Common errors](#common-errors). If the gateway can't be reached from the internet yet, select the **Skip the check** option, enter a **Reason for skipping**, and click **Connect without the check**. The reason is shown in the **Gateways** table, under the **Skipped** result's **Details**. Entering an address that is already registered runs the check again (unless you skip it) without changing the stored result, then moves to the bundle step.
7070 </Step>
7171
7272 <Step title="Add the gateway to an Access bundle">
73 Choose a bundle from the **Access bundle** list, or click **New bundle**, enter a **Bundle name**, and click **Create bundle**. Then click **Add to bundle**. This creates a connection in that bundle, labeled **Gateway** on its **Credentials** tab, with the gateway's host as its allowed website. A gateway can be in one bundle only; to use it in several scopes, attach that bundle to each. Click **Not now** to finish without a bundle.
73 Choose a bundle from the **Access bundle** list, or click **New bundle**, enter a **Bundle name**, and click **Create bundle**. Then click **Add to bundle**. This creates a connection in that bundle, labeled **Gateway** on its **Credentials** tab, with the gateway's host as its allowed website. A gateway can be in more than one bundle; the **Access bundle** list offers only the bundles it isn't in yet. Click **Not now** to finish without a bundle.
7474 </Step>
7575</Steps>
7676
77The **Gateways** table lists each gateway with its **Connection check** result (**Passed**, or **Skipped** with your reason), when it was added, and **Add to bundle** and **Remove** actions. For a gateway that is already registered, skip the dialog's first step: click **Add to bundle** in the gateway's row of the **Gateways** table, which opens the dialog at the bundle step. Entering the address again in **Connect a gateway** also reaches the bundle step, but unless you skip the check it runs again first, and that run counts toward the check limit.
77The **Gateways** table lists each gateway with its **Access bundles**, its **Connection check** result (**Passed**, or **Skipped**, with the reason you gave under **Details**), when it was added, and **Add to bundle** and **Remove** actions; on a row that is already in a bundle, the add action reads **Add to another bundle**. For a gateway that is already registered, skip the dialog's first step: click the add action in the gateway's row of the **Gateways** table, which opens the dialog at the bundle step. Entering the address again in **Connect a gateway** also reaches the bundle step, but unless you skip the check it runs again first, and that run counts toward the check limit.
7878
7979## Let agents reach the gateway
8080
from line 102
102102
103103If 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.
104104
105To disconnect a gateway, click **Remove** in the gateway's row of the **Gateways** table. Claude stops using the gateway at once. A token issued before the removal stays valid until it expires, within 10 minutes.
105To 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
109Two messages come up while connecting:
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).
110110
111* **"The check didn't pass"**: 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).
112* **A bundle-step message that the gateway is already in a bundle**: a gateway can be in one bundle only. [Attach that bundle to the scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead.
111A 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, [attach a bundle it's in to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle).
113112
114For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting).
113For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting).
115114
116115If 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 under the [scope](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit) of the Access bundle that holds the connection.
117116
from line 119
120119* [Give Claude access](/docs/claude-tag/admins/add-connections): the Access bundle and connection model
121120* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a gateway connection applies
122121* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation
123* [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
122* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
124123* [Sample gateway](https://github.com/anthropics/claude-tag-wif-gateway-sample): a reference gateway with offline tests
125124
claude-tag/admins/federated-access/gcp Changed · +5 / -5 lines
from line 6
66
77<BetaNote />
88
9<Note>Google Cloud identities are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Cloud roles** section. Connecting an identity needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
9<Note>Google Cloud identities are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated agent access** in the left navigation and use the **Cloud roles** section. Connecting an identity needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
1010
1111With a Google Cloud identity connection, Claude exchanges a short-lived identity token at a workload identity pool you create and calls Google Cloud APIs with the result. No service account key is stored in Claude. The token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel), and your pool's attribute condition decides which tokens to accept. If someone else manages your Google Cloud project, give them the values from Claude's admin settings and the settings below; the console steps need a Claude Tag admin.
1212
from line 21
2121
2222## Copy the values from the console
2323
24In **Cloud roles**, click **Connect a Google Cloud identity** and copy the **Issuer** and **Subject prefix** rows from the **Set the workload identity provider to accept these values** card (the **JWKS URL** row isn't needed, because Google reads the keys from the issuer). Then click **Cancel**; you connect the identity after setting up Google Cloud.
24In **Cloud roles**, click **Connect a Google Cloud identity** and copy the **Issuer** and **Subject prefix** rows from the **Set the workload identity provider to accept these values** card (the **JWKS URL** row isn't needed, because Google reads the keys from the issuer). The card also has a **Tenant ID for tokens** row with your organization ID, and an **Attribute condition** row holding the prefix form of the condition in [Create the pool and provider in Google Cloud](#create-the-pool-and-provider-in-google-cloud). Then click **Cancel**; you connect the identity after setting up Google Cloud.
2525
2626| Value | What it is |
2727| :- | :- |
from line 142
142142* A token refused by your provider usually means the attribute condition didn't accept it. Check the organization ID in the condition, then the issuer URL and the allowed audience.
143143* A permission error on the API call means the role grant is missing or too narrow.
144144
145See [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows and the other causes.
145See [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows and the other causes.
146146
147147To disconnect an identity, click **Remove** in the identity's row of the **Cloud roles** table, then **Remove role** in the confirmation. Claude stops using the identity within about a minute, in existing threads as well as new ones, and the connection is removed from its bundle. A Google credential from an earlier exchange stays valid with Google until it expires, held only by Agent Proxy, never by Claude's sandbox. To end the trust on the Google side as well, delete the provider or remove the IAM bindings.
148148
from line 153
153153* **A message that a connection "already covers" a host "in this bundle"**: another Google Cloud connection in the bundle you chose already has that host under **Allowed hosts**, so Claude would never use the new connection for it. Remove the shared host or choose another bundle.
154154* **A rejected Workload identity provider or Service account to act as value**: the value doesn't match the form the field describes, usually because the resource name carries the project ID instead of the project number, or the service account is a default one.
155155
156For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting).
156For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting).
157157
158158If 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 under the [scope](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit) of the Access bundle that holds the connection.
159159
from line 163
163163* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where an identity connection applies
164164* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation
165165* [Limits](/docs/claude-tag/admins/federated-access/limits): what the credential-minting block refuses, and the other limits for Google Cloud identities
166* [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
166* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
167167* [BigQuery](/docs/claude-tag/admins/connections/bigquery): the stored-key alternative for one Google service
168168
claude-tag/admins/federated-access/limits Changed · +3 / -4 lines
# Limits for federated agent access # Limits for federated cloud access
from line 1
1# Limits for federated cloud access
1# Limits for federated agent access
22
3> Counts, lengths, lifetimes, and unsupported configurations for Claude Tag's federated cloud access: gateways, AWS roles, Google Cloud identities, and authorization servers.
3> Counts, lengths, lifetimes, and unsupported configurations for Claude Tag's federated agent access: gateways, AWS roles, Google Cloud identities, and authorization servers.
44
55export const BetaNote = () => <Info>Claude Tag is in public beta. Features and behavior described here may change before general availability.</Info>;
66
77<BetaNote />
88
9This page collects the fixed limits of Federated cloud access in one place.
9This page collects the fixed limits of Federated agent access in one place.
1010
1111## Where federated connections work
1212
from line 27
2727| Registered addresses per organization | 5, counting gateways and authorization-server token endpoints together. |
2828| Token reuse | Claude reuses one token for a session's requests to the same gateway for about five minutes, half the token's lifetime, or until the gateway answers 401, and then requests a new one (current behavior, may change). A gateway sees the same `jti` on many requests. |
2929| Gateway address | An HTTPS host name only, with no path, port, query, or trailing slash. The host name needs a domain, like `gateway.example.com`, uses only letters, numbers, hyphens, and dots, and has at most 253 characters (current behavior, may change). The console rejects an IP address, a private-network name, an Anthropic-owned host, or a host cloud providers use for token exchange, and names the reason. The connection check also refuses a host name that resolves to a private address. |
30| One connection per gateway | A gateway connected in one Access bundle can't be connected again in another. Attach that bundle to each scope that needs the gateway. |
3130| [Allowed websites](/docs/claude-tag/admins/add-connections#set-allowed-websites) on the gateway's connection | Exactly the gateway's host, the only host Claude sends the token to. It can't be widened or given a wildcard. |
3231| Connection check | Runs only against an HTTPS host with no path. The console sends two `POST` requests to the address, each with an empty body and a test token, doesn't follow redirects, and can take up to a minute. [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway) lists the expected responses. The console refuses a check that runs many times in quick succession and says how long to wait. |
3332| Same address twice in one organization | Entering an address that is already registered runs the connection check again (unless you skip it) without changing the stored result, then moves to the bundle step. The run counts toward the check limit. |
claude-tag/admins/federated-access/overview Changed · +9 / -9 lines
# Federated agent access # Federated cloud access
from line 1
1# Federated cloud access
1# Federated agent access
22
33> Claude Tag proves its identity to your systems with a short-lived signed token instead of a credential stored in Claude. Learn how the token works and which of the four connection types to use.
44
from line 6
66
77<BetaNote />
88
9<Note>Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation. Connecting a gateway, cloud role, or authorization server needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
9<Note>Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated agent access** in the left navigation. Connecting a gateway, cloud role, or authorization server needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
1010
11In Slack channels, Claude Tag acts under its own [agent identity](/docs/claude-tag/concepts/agent-identity) rather than as any person. Federated cloud access lets that identity prove itself to your systems with a short-lived, signed identity token instead of a credential you store in Claude.
11In Slack channels, Claude Tag acts under its own [agent identity](/docs/claude-tag/concepts/agent-identity) rather than as any person. Federated agent access lets that identity prove itself to your systems with a short-lived, signed identity token instead of a credential you store in Claude.
1212
13In the console, you connect your gateway, AWS role, Google Cloud identity, or authorization server under **Federated cloud access** and add it to an [Access bundle](/docs/claude-tag/admins/add-connections) attached to the channels where Claude should use it. Your cloud or gateway administrator configures that system to trust Anthropic's issuer and to check that each token's subject belongs to your organization, and the system then decides what the agent may do. To confirm the connection works, ask Claude in one of those channels to make a small request, then check its reply and your system's logs.
13In the console, you connect your gateway, AWS role, Google Cloud identity, or authorization server under **Federated agent access** and add it to an [Access bundle](/docs/claude-tag/admins/add-connections) attached to the channels where Claude should use it. Your cloud or gateway administrator configures that system to trust Anthropic's issuer and to check that each token's subject belongs to your organization, and the system then decides what the agent may do. To confirm the connection works, ask Claude in one of those channels to make a small request, then check its reply and your system's logs.
1414
15Federated cloud access goes one way: Claude proves who it is to your systems. For your workloads proving who they are to the Claude API, see [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) on the Claude Developer Platform.
15Federated agent access goes one way: Claude proves who it is to your systems. For your workloads proving who they are to the Claude API, see [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) on the Claude Developer Platform.
1616
1717Your systems can accept the token in one of four ways. The table below says which to choose; the rest of the page explains what the token is and what to have ready.
1818
from line 29
2929
3030## How it works
3131
321. When a request from Claude's sandbox needs one of your systems, [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) matches it by destination to a federated connection in one of the channel's Access bundles. Until an admin connects a system in **Federated cloud access** and adds it to a bundle attached to the channel, nothing matches and no token is issued for Claude's requests.
321. When a request from Claude's sandbox needs one of your systems, [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) matches it by destination to a federated connection in one of the channel's Access bundles. Until an admin connects a system in **Federated agent access** and adds it to a bundle attached to the channel, nothing matches and no token is issued for Claude's requests.
33332. Anthropic issues an identity token. The token is a JSON Web Token (JWT) signed by Anthropic and valid for 10 minutes. Its subject names your organization and the agent, in the form `wimse://identity.anthropic.com/org/<your organization ID>/agent/<agent ID>`, and its audience names the destination. Claude reuses one token for a session's requests to the same gateway for about five minutes, or until the gateway answers 401, and then requests a new one. The other connection types use a token once, in an exchange.
34343. Your side accepts the token. A gateway verifies it directly. AWS or Google Cloud exchanges it for a short-lived cloud credential. Your authorization server exchanges it for an access token. Agent Proxy attaches the result to Claude's request, or signs the request with it for AWS, and forwards the request. The model and the sandbox are never given the token or the credential that comes back.
3535
from line 58
5858
5959## Before you begin
6060
61* **Federated cloud access** appears in the console's left navigation. It's missing for organizations whose compliance configuration excludes federated cloud access.
61* **Federated agent access** appears in the console's left navigation. It's missing for organizations whose compliance configuration excludes federated agent access.
6262* An organization Owner, or an admin with full Claude Tag management permission, makes the connection in the console.
6363* Your cloud or gateway administrator configures the system on your side: the gateway operator, your AWS or Google Cloud IAM administrator, or your authorization server's operator. Each setup page lists the values they configure.
64* An [Access bundle](/docs/claude-tag/admins/add-connections) is attached to the [scope](/docs/claude-tag/concepts/glossary#scope) of the channels where Claude should use the connection. A connection can be in only one bundle, so to use a connection in several places, attach that bundle to each scope.
64* An [Access bundle](/docs/claude-tag/admins/add-connections) is attached to the [scope](/docs/claude-tag/concepts/glossary#scope) of the channels where Claude should use the connection. To use a connection in several places, attach its bundle to each scope. A gateway can also be added to more than one bundle; an AWS role or authorization server is connected in one bundle only.
6565
6666Federated connections work in Slack channels, where Claude acts under your organization's agent identity. They don't work in direct messages from members who have connected a Claude account, which run under [the individual's own account](/docs/claude-tag/concepts/agent-identity#direct-message-channels).
6767
from line 74
7474* [Connect an authorization server](/docs/claude-tag/admins/federated-access/authorization-server): accept the token as a JWT bearer grant
7575* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim, the lifetime, and key rotation
7676* [Limits](/docs/claude-tag/admins/federated-access/limits): counts, lengths, lifetimes, and unsupported configurations
77* [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console messages, blocked requests, and rejections in your logs
77* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting): console messages, blocked requests, and rejections in your logs
7878
claude-tag/admins/federated-access/troubleshooting Changed · +16 / -16 lines
# Troubleshoot federated agent access # Troubleshoot federated cloud access
from line 1
1# Troubleshoot federated cloud access
1# Troubleshoot federated agent access
22
3> Errors from Claude Tag's federated cloud access and what fixes each: console dialog messages, requests Claude reports as blocked or failed, and rejections your gateway, AWS, Google Cloud, or authorization server records.
3> Errors from Claude Tag's federated agent access and what fixes each: console dialog messages, requests Claude reports as blocked or failed, and rejections your gateway, AWS, Google Cloud, or authorization server records.
44
55export const BetaNote = () => <Info>Claude Tag is in public beta. Features and behavior described here may change before general availability.</Info>;
66
77<BetaNote />
88
9<Note>Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation. Changing them needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
9<Note>Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated agent access** in the left navigation. Changing them needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
1010
11This page covers what goes wrong after you connect a gateway, AWS role, Google Cloud identity, or authorization server through **Federated cloud access**. It's organized by where the problem shows up: a message in a console dialog, an error Claude reports in the thread, or a rejection in your own logs. The token terms used below are explained on the [identity token reference](/docs/claude-tag/admins/federated-access/token-reference).
11This page covers what goes wrong after you connect a gateway, AWS role, Google Cloud identity, or authorization server through **Federated agent access**. It's organized by where the problem shows up: a message in a console dialog, an error Claude reports in the thread, or a rejection in your own logs. The token terms used below are explained on the [identity token reference](/docs/claude-tag/admins/federated-access/token-reference).
1212
1313First confirm two things that have nothing to do with federation:
1414
from line 24
2424| Message | What it means | Do this |
2525| :- | :- | :- |
2626| "The check can't run right now. Try again later, or skip the check and record why." | Anthropic couldn't produce the test tokens for the connection check. The problem is on Anthropic's side, not your gateway's. | Wait a few minutes and click **Run check and connect** again. If the message persists, select the **Skip the check** option, enter a **Reason for skipping**, and click **Connect without the check**; remove and reconnect the gateway later to record a passed check. |
27| "Too many checks in a short time." followed by how long to wait | Your organization ran the connection check too many times in quick succession. The limit counts every admin in the organization. Entering an address that is already registered runs the check again and counts too, unless the **Skip the check** option is selected. | Wait the time the message names. To add an existing gateway to a bundle, click **Add to bundle** in its row of the **Gateways** table instead of entering its address again. |
27| "Too many checks in a short time." followed by how long to wait | Your organization ran the connection check too many times in quick succession. The limit counts every admin in the organization. Entering an address that is already registered runs the check again and counts too, unless the **Skip the check** option is selected. | Wait the time the message names. To add an existing gateway to a bundle, click **Add to bundle** (**Add to another bundle** on a row already in one) in the **Gateways** table instead of entering its address again. |
2828| "Too many attempts in a short time." in the **Connect an authorization server** dialog | A general request limit, not the connection check; registering a token endpoint never runs the check. | Wait the time the message names and try again. |
2929| "Connecting a gateway needs full Claude Tag management permission. Ask an organization owner." or "This needs full Claude Tag management permission. Ask an organization owner." | Your account can't change federated connections. Channel managers, and admins whose Claude Tag permission covers specific channels only, can't connect a gateway, cloud role, or authorization server. | Ask an organization Owner, or an admin with full Claude Tag management permission, to make the connection from their own account. |
30| A dialog message containing "isn't enabled for your organization yet", or **Federated cloud access** is missing from the left navigation | Federated cloud access isn't available to organizations whose compliance configuration excludes it. The navigation item is also hidden from channel managers and from admins whose Claude Tag permission covers specific channels only, because connecting a system needs full Claude Tag management permission. | Ask an organization Owner, or an admin with full Claude Tag management permission, to open the page. If it's missing for them too, your organization's compliance configuration excludes the feature. |
30| A dialog message containing "isn't enabled for your organization yet", or **Federated agent access** is missing from the left navigation | Federated agent access isn't available to organizations whose compliance configuration excludes it. The navigation item is also hidden from channel managers and from admins whose Claude Tag permission covers specific channels only, because connecting a system needs full Claude Tag management permission. | Ask an organization Owner, or an admin with full Claude Tag management permission, to open the page. If it's missing for them too, your organization's compliance configuration excludes the feature. |
3131| "This organization has reached its limit of 5 gateways. Remove one to connect another." or, in the **Connect an authorization server** dialog, "…limit of 5 registered gateways, which includes token endpoints." | An organization can register 5 addresses. A token endpoint is registered the same way as a gateway, so it counts toward the same 5 and appears in the **Gateways** table marked "Used by a connected authorization server. Manage it from the Authorization servers section." An address is either a gateway or a token endpoint in your organization, not both. | In the **Gateways** table, click **Remove** in the row of a gateway you no longer use. To free a token endpoint's row, click **Remove** in the server's row of the **Authorization servers** table first, then remove the endpoint from the **Gateways** table. See [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). |
32| "This gateway is already registered. Close this dialog and pick it from the list to add it to a bundle." | The address is already registered in your organization, and the dialog couldn't load its row to continue. This message is rare: entering a registered address normally runs the connection check again without changing the stored result, then moves on to the bundle step. | Click **Cancel**, then click **Add to bundle** in the gateway's row of the **Gateways** table. |
33| "`<address>` is already in the bundle `<bundle>`. Assign that bundle to a channel to use the gateway there.", "This role is already connected in the bundle `<bundle>`.", or "This token endpoint is already connected in the bundle `<bundle>`." | A gateway, AWS role, or token endpoint can be connected in only one Access bundle, and this one already is. | To use the connection in more channels, [attach that bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. To move it, in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, and choose **Delete**. Then add it to the new bundle: **Add to bundle** in the gateway's row of the **Gateways** table, or the connect dialog again for the other types. |
32| "This gateway is already registered. Close this dialog and pick it from the list to add it to a bundle." | The address is already registered in your organization, and the dialog couldn't load its row to continue. This message is rare: entering a registered address normally runs the connection check again without changing the stored result, then moves on to the bundle step. | Click **Cancel**, then click **Add to bundle** (**Add to another bundle** on a row already in one) in the gateway's row of the **Gateways** table. |
33| "This role is already connected in the bundle `<bundle>`." or "This token endpoint is already connected in the bundle `<bundle>`." | An AWS role or token endpoint can be connected in only one Access bundle, and this one already is. | To use the connection in more channels, [attach that bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. To move it, in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, and choose **Delete**. Then connect it again from its own dialog and pick the new bundle. |
3434| "`<name>` already covers `<host>` in this bundle, so Claude would never use this connection for the hosts they share. Change the hosts or choose another bundle." in the **Connect a Google Cloud identity** dialog | Another Google Cloud connection in the bundle you chose already has that host under **Allowed hosts**, whatever its provider or service account. Claude uses the first connection in a bundle whose hosts match a request, so the new connection would never be used for the shared host. A wildcard such as `*.googleapis.com` covers every subdomain but not `googleapis.com` itself. The dialog won't connect until the overlap is gone. | Remove the shared host from the new connection's **Allowed Google hosts**, or choose another bundle. To give the host to the new connection instead, first narrow the existing one: in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, choose **Edit**, and change **Allowed hosts**. |
3535| "Couldn't connect the gateway. Try again.", "Couldn't add the gateway to the bundle.", "Couldn't connect the role. Try again.", "Couldn't connect the identity. Try again.", "Couldn't register the authorization server. Try again.", or "Couldn't connect the authorization server. Try again." | The request failed for a reason the dialog doesn't name, most often a temporary one. | Try once more. If the message persists, contact your Anthropic account team with the details under [Contact Anthropic](#contact-anthropic). |
3636| "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." in the **Connect an authorization server** dialog | The **Issuer URL** value must be an HTTPS URL on the same host as the token endpoint, or empty. The token is only ever presented to that server, so its audience must name that server. | Enter the issuer identifier your authorization server uses, on the token endpoint's host, or clear the field to use the token endpoint as the audience. |
3737| "This token endpoint is already connected. Manage it from the Authorization servers section." in the **Connect an authorization server** dialog | An authorization server with this token endpoint is already connected in one of your organization's Access bundles, and a server can be connected only once. The dialog checks this before it registers anything. | To use the server in more channels, [attach its bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle). To connect it again, remove it first: in the **Authorization servers** table, click **Remove** in the server's row. |
38| "That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first." in the **Connect an authorization server** dialog | The token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your organization's Access bundles. One address can't be both, because a token sent to the gateway could be replayed to the server as a grant. | Enter the token endpoint and issuer identifier your authorization server publishes. To use that address for the server instead, remove the gateway first: in **Access bundles**, open the bundle that holds the gateway, open its **Credentials** tab, open the **⋮** menu on the gateway's row, and choose **Delete**. Then, in the **Gateways** table under **Federated cloud access**, click **Remove** in the gateway's row. |
38| "That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first." in the **Connect an authorization server** dialog | The token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your organization's Access bundles. One address can't be both, because a token sent to the gateway could be replayed to the server as a grant. | Enter the token endpoint and issuer identifier your authorization server publishes. To use that address for the server instead, remove the gateway first: in **Access bundles**, open the bundle that holds the gateway, open its **Credentials** tab, open the **⋮** menu on the gateway's row, and choose **Delete**. Then, in the **Gateways** table under **Federated agent access**, click **Remove** in the gateway's row. |
3939| "That address is registered by a connected authorization server. Enter your gateway's address, or remove the server first." in the **Connect a gateway** dialog | The address you entered is a connected authorization server's token endpoint or audience, for example a server whose **Issuer URL** is the bare host `https://auth.example.com`. One address can't be both, because a token sent to the gateway could be replayed to that server as a grant. | Enter the host your gateway answers on. To use that address for a gateway instead, remove the server first: in the **Authorization servers** table, click **Remove** in the server's row. |
4040| "That address is already a connected authorization server's audience. Enter this server's own issuer URL." in the **Connect an authorization server** dialog | The **Issuer URL** value (or the token endpoint, when **Issuer URL** is empty) is already another connected authorization server's audience or token endpoint. Two servers can't share an audience, because a token minted for one would be valid at the other. | In the **Issuer URL** field, enter the issuer identifier this server publishes. If the other server holds this identifier by mistake, remove that server first: in the **Authorization servers** table, click **Remove** in its row, then connect it again with its own issuer URL. |
4141| "The address is too long. Issuer URLs have at most 256 characters." under the **Issuer URL** field of the **Connect an authorization server** dialog | The **Issuer URL** field accepts at most 256 characters, the same limit as the **Token endpoint** field. | Check that the field holds only the issuer identifier, for example `https://auth.example.com`, and not a longer value pasted by mistake. |
from line 69
6969
7070### Removing and reconnecting a gateway
7171
72In the **Gateways** table, click **Remove** in the gateway's row. Claude stops using the gateway at once. A connection that used the gateway stays in its Access bundle but stops working, and Claude reports [request blocked: this credential's audience isn't registered as a gateway for this organization](#request-blocked-this-credential%E2%80%99s-audience-isn%E2%80%99t-registered-as-a-gateway-for-this-organization) until the gateway is registered again.
72In the **Gateways** table, click **Remove** in the gateway's row and confirm with **Remove gateway**. Claude stops using the gateway at once. A connection that used the gateway stays in its Access bundle but stops working, and Claude reports [request blocked: this credential's audience isn't registered as a gateway for this organization](#request-blocked-this-credential%E2%80%99s-audience-isn%E2%80%99t-registered-as-a-gateway-for-this-organization) until the gateway is registered again.
7373
74To reconnect, click **Connect a gateway** in the **Gateways** section and enter the same address. Registering the address restores the existing connection, which is still in the bundle, so don't add it to the bundle again; the dialog refuses if you try.
74To reconnect, click **Connect a gateway** in the **Gateways** section and enter the same address. Registering the address restores the existing connection, which is still in the bundle; the bundle step then offers only bundles the gateway isn't in.
7575
7676## Errors Claude reports in the thread
7777
from line 366
366366
367367## Related resources
368368
369* [Federated cloud access overview](/docs/claude-tag/admins/federated-access/overview): how the token works and which connection type to use
369* [Federated agent access overview](/docs/claude-tag/admins/federated-access/overview): how the token works and which connection type to use
370370* [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway): the setup steps and the connection check in full
371371* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim, the lifetime, and key rotation
372372* [Limits](/docs/claude-tag/admins/federated-access/limits): counts, lengths, and lifetimes
373* [Troubleshoot Claude Tag setup](/docs/claude-tag/admins/troubleshooting): errors outside federated cloud access
373* [Troubleshoot Claude Tag setup](/docs/claude-tag/admins/troubleshooting): errors outside federated agent access
374374
claude-science/manage-on-devices Changed · +1 / -1 lines
from line 39
3939To turn telemetry and error reports off on managed devices, use either of:
4040
4141Set disable\_telemetry = true in config.toml (deployable through MDM).\
42Set the DO\_NOT\_TRACK environment variable (for example to 1) on the device.
42Set the DO\_NOT\_TRACK environment variable (for example to 1) where the app reads it at launch. See [How the environment variables reach the app](/docs/claude-science/corporate-networks#how-the-environment-variables-reach-the-app).
4343
4444Both are device-level settings. There's no per-member or per-organization telemetry toggle in Organization settings.
4545
claude-tag/admins/federated-access/token-reference Changed · +2 / -2 lines
from line 6
66
77<BetaNote />
88
9When Claude calls a system you connected through Federated cloud access, it proves who it is with a signed identity token instead of a stored credential. The token is a JSON Web Token (JWT) that names your organization and the agent making the request. A gateway you run receives it in the `Authorization: Bearer` header and verifies it directly. AWS, Google Cloud, or your authorization server receives it in a token exchange and returns one of its own credentials.
9When Claude calls a system you connected through Federated agent access, it proves who it is with a signed identity token instead of a stored credential. The token is a JSON Web Token (JWT) that names your organization and the agent making the request. A gateway you run receives it in the `Authorization: Bearer` header and verifies it directly. AWS, Google Cloud, or your authorization server receives it in a token exchange and returns one of its own credentials.
1010
1111This page lists what the token contains so the engineer who configures the verifying side can pin the right values. For setup steps, see [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway), [Connect an AWS role](/docs/claude-tag/admins/federated-access/aws), [Connect a Google Cloud identity](/docs/claude-tag/admins/federated-access/gcp), or [Connect an authorization server](/docs/claude-tag/admins/federated-access/authorization-server).
1212
from line 97
9797
9898Three claim names are reserved and absent from every token: `platform_user_id`, `actor_sub`, and `account_id`. Don't write a rule that depends on them. An absent claim is omitted from the token, never sent empty.
9999
100Anthropic sends the token only to the destinations you connect in **Federated cloud access**. When the request comes from Slack, the `slack_workspace_id` and `slack_channel_id` claims carry your Slack workspace and channel IDs to that destination along with your organization and agent IDs.
100Anthropic sends the token only to the destinations you connect in **Federated agent access**. When the request comes from Slack, the `slack_workspace_id` and `slack_channel_id` claims carry your Slack workspace and channel IDs to that destination along with your organization and agent IDs.
101101
102102Authorize on `sub`, as described under [Authorize on the subject](#authorize-on-the-subject). A gateway or authorization server, which can read every claim, can use `tenant` and `agent_id` instead, because they repeat the subject's two parts. An AWS trust policy matches on `sub` and `aud` only; a Google Cloud attribute condition can read `sub` or `tenant`. The token carries no claim that names the person behind the request, and no `groups`, `roles`, or `scope` claims. A rule that needs `slack_workspace_id` or `slack_channel_id` should refuse a token that lacks them.
103103