Files
coder/docs/workspaces/workspace-access/claude-code-subscription.md
T
coder[bot]andCoder Prototypes 5e711930f7 docs: add Claude Code subscription sign-in guide for workspaces (#31805)
Adds a how-to page for using a Claude subscription with Claude Code
inside a Coder workspace, rather than an Anthropic API key. Until now
the docs covered API keys, other providers, and AI Gateway, but not this
path.

New page: `docs/workspaces/workspace-access/claude-code-subscription.md`
(added to the sidebar under Workspace access, after Claude Desktop).

- **Interactive sign-in:** `claude auth login` (or `/login`), open the
printed URL locally, paste the code back. A fallback section covers
forwarding the `localhost` callback port with `coder port-forward` or
`ssh -L` when a local browser gets redirected to the workspace.
- **Long-lived token:** `claude setup-token`, stored as a Coder user
secret injected as `CLAUDE_CODE_OAUTH_TOKEN`. Also covers the Claude
Code module's `claude_code_oauth_token` input for template admins, and
notes that a template-level token is shared by every user of that
template.
- **Troubleshooting:** `ANTHROPIC_API_KEY` takes precedence over the
subscription. Confirm with `claude auth status --text` or `/status`,
then `unset` the key. Also lists where Coder can set the key (user
secret, dotfiles, template). Notes that `ANTHROPIC_AUTH_TOKEN` (AI
Gateway) also takes precedence.
- **Cross-links** from `templates/extending-templates/modules.md` (AI
agent modules), `ai-governance/ai-gateway/clients/claude-code.md` (BYOK
Claude subscription), and
`workspaces/workspace-access/claude-desktop.md` (next steps).

Claude Code behavior (precedence, `setup-token`, plan requirements)
links to Anthropic's docs instead of restating plan details.

**These steps were not tested with a real Claude subscription.** I ran
Claude Code 2.1.318 in a Linux workspace without completing a sign-in. I
captured the `claude auth login` prompt and the redirect targets of both
the printed and the browser-opened URLs. I also captured `claude auth
status` output with dummy `CLAUDE_CODE_OAUTH_TOKEN` and
`ANTHROPIC_API_KEY` values to confirm precedence.

<details>
<summary>Decision log</summary>

- **Paste-code flow first, port forwarding as fallback.** The URL that
`claude auth login` prints redirects to
`https://platform.claude.com/oauth/code/callback`, which shows a code to
paste, so SSH users don't need to forward a port. Only the URL handed to
`$BROWSER` redirects to `http://localhost:<random-port>/callback`. The
ticket described port forwarding as the main path.
- **Page location.** No Claude Code page exists under Workspaces. Claude
Code in workspaces is only mentioned in `modules.md` and the AI Gateway
client page. The page sits next to Claude Desktop, and those pages link
to it.
- **User secret over template input for the token.** A subscription
token belongs to one person. A user secret is per user and overrides
`coder_env` with the same name. The template input is still documented
for admins, with the sharing caveat.

</details>

### Verified against
- `coder/registry`: `registry/coder/modules/claude-code/main.tf` and
`README.md` (main, v5.5.2). `claude_code_oauth_token` is sensitive and
sets `CLAUDE_CODE_OAUTH_TOKEN`. It exists in v5.2.0, which matches the
docs' `~> 5.2` pin. Plan-time validation rejects it together with
`enable_ai_gateway` or `api_key_helper`.
- `cli/portforward.go` and
`docs/workspaces/workspace-access/port-forwarding.md`: `--tcp` syntax
and the `ssh -L` section anchor.
- `cli/secret.go`, `docs/workspaces/user-secrets.md`,
`site/src/pages/UserSettingsPage/SecretsPage/SecretDialog.tsx` and
`SecretsPageView.tsx`: Account > Secrets, **Add secret**, the **Name**,
**Value**, and **Environment variable** field labels, **Save**, and
user-secret precedence over `coder_env`.
- Anthropic's Claude Code docs: `authentication` (log in, credential
storage, authentication precedence, generate a long-lived token) and
`cli-reference` (`claude auth login`, `claude auth status`, `claude
setup-token`).
- Local runs of Claude Code 2.1.318 as described above.

### Open questions for the reviewer
- Nobody has completed either flow with a real Pro or Max account.
Someone with a subscription should check the paste-code flow end to end,
and that `claude auth status` then shows `"authMethod": "claude.ai"`
(the value comes from Anthropic's CLI reference).
- The port-forward fallback says to reload the failed `localhost`
callback page after starting `coder port-forward`. I haven't confirmed
that the reload completes the sign-in instead of needing a fresh `claude
auth login`.
- The acceptance criteria ask for a link back from the registry module
page. That README lives in `coder/registry` and needs a separate PR
there.
- Should the template example have a callout about whether sharing one
subscription token across users is acceptable? The page currently only
states the consequence.

Generated by Coder Agents.

Closes DOCS-510

Co-authored-by: Coder Prototypes <294797144+coder-prototypes@users.noreply.github.com>
2026-11-06 17:24:33 -05:00

7.1 KiB

title
title
Sign in to Claude Code with a Claude subscription

Use your Claude subscription to authenticate Claude Code in a Coder workspace, instead of an Anthropic API key. This guide is for developers who run the Claude Code CLI in a workspace terminal.

Claude Code in a workspace is the same CLI that you run on your local machine. When no other credential is set, Claude Code uses your subscription sign-in. Anthropic's authentication precedence lists the order in which Claude Code picks a credential.

You can authenticate in one of two ways:

Prerequisites

Sign in interactively

  1. Open a terminal in your workspace:

    coder ssh <workspace-name>
    
  2. Start the sign-in:

    claude auth login
    

    Claude Code prints a sign-in URL and waits for a code:

    Opening browser to sign in…
    If the browser didn't open, visit: https://claude.com/cai/oauth/authorize?...
    Paste code here if prompted >
    

    You can also run claude and then type /login at the Claude Code prompt.

  3. Open the sign-in URL in the browser on your local machine.

  4. Sign in with your Claude account and approve access.

  5. Copy the code that the browser shows.

  6. Paste the code at the Paste code here if prompted prompt in the workspace terminal.

  7. Confirm the sign-in:

    claude auth status
    

    The output shows "loggedIn": true and "authMethod": "claude.ai".

Claude Code saves your sign-in to ~/.claude/.credentials.json in the workspace. If your template does not keep your home directory between workspace restarts, sign in again after each restart, or use a long-lived token.

Forward the sign-in port

When Claude Code can open a browser on your local machine, for example from your IDE's terminal, the sign-in redirects to a localhost address instead of showing a code. That address points to a port in the workspace, such as http://localhost:39437/callback. Claude Code picks a new port for each sign-in. Some IDEs forward the port for you.

If the localhost page fails to load after you approve access:

  1. Note the port number in the localhost address.

  2. On your local machine, forward the port from the workspace and leave the command running:

    coder port-forward <workspace-name> --tcp <port>
    
  3. Reload the localhost page in your browser.

You can also forward the port over SSH with ssh -L.

Use a long-lived token

A long-lived token lets Claude Code authenticate without a browser, so every workspace you own can start Claude Code already signed in.

  1. Generate a token with Claude Code, on your local machine or in a workspace:

    claude setup-token
    

    The command opens the same sign-in flow as claude auth login and prints a token when you approve access. Claude Code does not save the token. Refer to Anthropic's long-lived token documentation for its requirements and limits.

  2. Copy the token.

  3. In the Coder dashboard, select your avatar, then select Account > Secrets.

  4. Select Add secret.

  5. Enter a Name, such as claude-code-oauth-token.

  6. Paste the token into Value.

  7. Enter CLAUDE_CODE_OAUTH_TOKEN in Environment variable.

  8. Select Save.

  9. Restart your workspace.

  10. Confirm that Claude Code reads the token:

    claude auth status --text
    
    Auth token: CLAUDE_CODE_OAUTH_TOKEN
    

Coder injects the secret into every workspace you own. To manage the secret from the CLI instead, refer to User secrets.

Set the token in a template

Template administrators can pass a token to the Claude Code module with its claude_code_oauth_token input. The module sets CLAUDE_CODE_OAUTH_TOKEN in every workspace that the template creates, so every user of the template shares the same subscription. For a token per user, have each user store it as a user secret. A user secret overrides an environment variable with the same name that the template sets.

variable "claude_code_oauth_token" {
  type      = string
  sensitive = true
}

module "claude-code" {
  source                  = "registry.coder.com/coder/claude-code/coder"
  version                 = "~> 5.2"
  agent_id                = coder_agent.main.id
  claude_code_oauth_token = var.claude_code_oauth_token
}

Set only one authentication input on the module. The module rejects claude_code_oauth_token together with enable_ai_gateway or api_key_helper.

Troubleshooting

Claude Code uses an API key instead of your subscription

When ANTHROPIC_API_KEY is set, it takes precedence over your subscription sign-in and your token. In an interactive session, Claude Code asks once whether to use the key. If the key belongs to a disabled or expired organization, requests fail with authentication errors.

  1. Check which credential Claude Code uses:

    claude auth status --text
    

    This output shows that the API key overrides the token:

    Auth token: CLAUDE_CODE_OAUTH_TOKEN · not in use
    API key: ANTHROPIC_API_KEY
    
  2. Remove the API key from your shell:

    unset ANTHROPIC_API_KEY
    
  3. Start Claude Code and type /status to confirm that it uses your subscription.

unset affects only the current shell. If ANTHROPIC_API_KEY returns in new shells, remove it where it's set, such as a user secret, your dotfiles, or the template. If your template sets it, ask your template administrator to remove the anthropic_api_key input from the Claude Code module.

ANTHROPIC_AUTH_TOKEN also overrides your subscription. When a template enables AI Gateway for Claude Code, Claude Code authenticates with AI Gateway through this variable.

Learn more