26 KiB
Claude Code gateway protocol
This is the wire contract the Claude Code CLI uses to talk to this gateway: sign-in, inference, managed settings, and telemetry. It's served from the gateway itself so it always matches the version you're running.
Stability: this protocol exists to give you a more stable target than proxying raw CLI traffic. Auth is standard OAuth 2.0, inference is the Messages API, and headers are the lowest common denominator across backends. We keep it backwards compatible within reason to support older clients, but not forever — expect changes, managed settings in particular, with notice.
A developer points Claude Code at your gateway's base URL via /login and
the client does the rest. All paths below are relative to that base URL, and
the client does not follow cross-origin redirects.
Flow
- Client fetches
GET {base}/.well-known/oauth-authorization-server. - On first contact, client fingerprints your TLS certificate and asks the user to trust it.
- Client runs the RFC 8628 device flow:
POST device_authorization_endpoint-> user approves in a browser atverification_uri-> client pollstoken_endpointuntil it gets a bearer token. - Client sends
Authorization: Bearer <token>on every subsequent request. - Client uses fixed paths under
{base}for inference (/v1/messages), policy (/managed/settings), model discovery (/v1/models), and telemetry (/v1/{metrics,logs,traces}). - Before the token expires, client silently calls
token_endpointwithgrant_type=refresh_token. If you didn't issue a refresh token, the user is sent back through the browser flow instead.
Don't reject what you don't recognize. New optional request parameters, body
fields and headers can appear in any Claude Code release, and many developer
machines update on their own, so a server that rejects unknown input can stop
working for its users from one day to the next. On the sign-in endpoints
ignore them (RFC 6749 §3.2 and RFC 8628 §3.1 require that for request
parameters). On /v1/messages pass body fields and anthropic-beta values
to your upstream unchanged (except request tags, below), and forward or drop
other headers, but never fail the request over them.
Discovery — required
GET /.well-known/oauth-authorization-server (unauthenticated)
RFC 8414 authorization server metadata. The client reads
device_authorization_endpoint and token_endpoint and, when present,
revocation_endpoint, and ignores the rest. It uses each only when it is an
absolute URL on the same origin as {base}; otherwise it sends the request
to {base}/oauth/device_authorization or {base}/oauth/token instead, and
skips revocation. So a gateway reached through a reverse proxy on another
hostname works when the proxy serves every path on this page, those two
included, and verification_uri is one the user's browser can open.
With a revocation_endpoint, sign-out sends
POST {revocation_endpoint} form-encoded with token=<bearer> and, when
you issued a refresh token, a second request with token=<refresh_token>
and token_type_hint=refresh_token (RFC 7009, no client authentication,
best effort); answer directly, the client follows no redirect here. A client
signed in before you advertised revocation_endpoint reads the metadata
again at sign-out. Answer a revoked bearer's next request with 401 and
x-should-retry: false (see Errors).
authorization_endpoint is intentionally absent.
{
"issuer": "https://gw.corp.example.com",
"device_authorization_endpoint": "https://gw.corp.example.com/oauth/device_authorization",
"token_endpoint": "https://gw.corp.example.com/oauth/token",
"grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}
Device authorization — required
POST {device_authorization_endpoint} (unauthenticated; answer directly, the
client follows no redirect here)
RFC 8628 §3.2. The client opens verification_uri_complete in the user's
browser and polls token_endpoint every interval seconds.
{
"device_code": "AbK9-s3n4C8H...",
"user_code": "WDJB-MJHT",
"verification_uri": "https://gw.corp.example.com/device",
"verification_uri_complete": "https://gw.corp.example.com/device?user_code=WDJB-MJHT",
"expires_in": 600,
"interval": 5
}
device_code should be >=256 bits, opaque, single-use. user_code should
use a base-20 charset (RFC 8628 §6.1).
The response may carry one optional extension, login_notice: a plain-text
string (≤500 chars) the client shows next to the code on its sign-in screen.
The request body is form-encoded and may carry one extension parameter next
to RFC 8628 §3.1's: surface, a stable identifier of the client application
that is signing in. Claude Code sends surface=claude_code. Record it if you
attribute sessions by client; otherwise ignore it, as OAuth servers do for
any parameter they do not recognize (RFC 6749 §3.1, §3.2). Today that is the
whole form: Claude Code sends no client_id or scope, here or at the token
endpoint, so don't require them. Don't require the form to be empty or to
hold only this field either. Claude Code also sends
User-Agent: claude-code/<version> on the metadata, device, token, refresh
and revoke requests.
Verification page — required
GET/POST {verification_uri} (browser-facing; the client never calls this)
Accept the user code, authenticate the user against your IdP, and mark the
matching device_code approved so the next token poll succeeds. Apply a
per-IP rate limit (RFC 8628 §5.1) and don't auto-submit a pre-filled code
(§5.4).
Token — required
POST {token_endpoint} (unauthenticated,
application/x-www-form-urlencoded; answer directly, the client follows no
redirect here)
Device grant (grant_type=urn:ietf:params:oauth:grant-type:device_code):
| Status | Body | Client reaction |
|---|---|---|
| 200 | {"access_token","token_type":"Bearer","expires_in","refresh_token"?,"email"?} |
Login complete. refresh_token is optional; omit it and the client re-runs the device flow on expiry. email is an extension: the account that approved the code. When present and non-blank, the client shows it and asks the user to confirm it before storing the credential, then shows it in /status. |
| 400 | {"error":"authorization_pending"} |
Keep polling. |
| 400/429 | {"error":"slow_down"} |
Add 5s to the poll interval. |
| 400 | {"error":"access_denied"} |
Stop. |
| 400 | {"error":"expired_token"} |
Stop. |
Refresh grant (grant_type=refresh_token): return a fresh
{"access_token","token_type","expires_in","refresh_token"} on 200. Return
401 {"error":"invalid_grant"} to force re-login — this is your
deprovisioning hook.
Messages — required
POST /v1/messages and POST /v1/messages/count_tokens (bearer)
The Anthropic Messages API (https://platform.claude.com/docs/en/api/messages),
unchanged. Proxy to your upstream and stream the response back. Enforce your
model allowlist here, returning 400 invalid_request_error for a denied
model. Don't buffer SSE on the stream: true path. The client always sets
Content-Length, so you may reject chunked-without-CL (411) and cap body
size (413). The client doesn't assume server-side tools are available. The
client also sends x-app and x-stainless-* headers — pass them through or
drop them, but don't reject the request because of them.
In auto mode the client adds an anthropic-beta value and a top-level
safeguards field, asking the upstream to run auto mode's safety check, and
reads safeguard_results from the reply. Pass all three through unchanged.
If you or your upstream can't, answer 400 invalid_request_error with a
message that names safeguards: the client retries without them and runs the
check itself with ordinary requests.
Managed settings — optional
GET /managed/settings (bearer)
Return {"uuid": "<id>", "checksum": "<checksum>", "settings": {...}}, where
settings is the authenticated user's Claude Code managed-settings.json;
see https://code.claude.com/docs/en/settings for the key reference. A 200
without that wrapper counts as a failed fetch. The client polls about once an
hour and sends If-None-Match: "<checksum>", a value it computes from the
settings it holds: sha256: plus the hex SHA-256 of the settings JSON with
keys sorted at every level and no whitespace. Use that value as your
checksum and, quoted, your ETag, and answer 304 on a match to keep
polling cheap; answering 200 every time also works. Send 304 only in
answer to an If-None-Match: the client counts one it didn't ask for as a
failed fetch. Return 404 for "no managed policy"; 200 with an empty
settings object means "this user has an empty policy" — they're not the
same. This is the endpoint most likely to change.
A Claude Desktop Code tab session on a machine that doesn't take your settings
sends the same request with If-None-Match: * at its start. It asks only
whether you have settings for that session: it reads no body and applies
nothing. Answer as you would without the header. On a 200, a 304 or a 404
the session starts and shows a warning that your settings may not apply. On a
429, a 5xx or no answer within 3 seconds it doesn't start. An answer that
carries both x-cc-gateway-version and Cache-Control: no-store is read more
closely: such a 404 says "nothing for this session", so no warning is shown,
and such a 304 says "there are settings that must not be missing", so the
session doesn't start. Send the two together only if you mean that.
Serve "CLAUDE_CODE_GATEWAY_HINT_HEADERS": "1" in the env block to learn,
on each model request, which managed settings the session runs under, so you can
find machines whose settings are out of date, edited or missing (an older client
may send no checksum). The client then sends the hint headers listed at
https://code.claude.com/docs/en/llm-gateway-protocol#gateway-hint-headers and
x-claude-code-managed-settings-checksum, computed the same way as the
If-None-Match value above, over the managed settings as the client loaded
them. In an interactive session the developer is asked to approve the variable
before it takes effect (if they decline, Claude Code exits); claude -p and
Agent SDK runs apply it without asking.
To use it, record the values that correctly set-up machines send and accept only those. Expect more than one value per policy:
- It can differ from the
checksumyou serve: the client changes some values as it loads them, a managed settings file or MDM profile on the machine can addenventries, and Claude Desktop can add restrictions and drop model settings. - After you edit your settings, keep accepting the previous value for at least
an hour, until every session has polled again. A session whose sign-in has
expired stops polling: once a
/loginin another terminal lets it carry on, its first requests still send the value from before the expiry.
A session that sends its requests through ANTHROPIC_UNIX_SOCKET, as
claude ssh does, sends no checksum. Treat a missing checksum like an unknown
one.
The checksum doesn't prove what a machine runs. The client computes it itself,
and anyone with a bearer token can send any value (with curl or an
ANTHROPIC_CUSTOM_HEADERS line). Use it to find stale or unmanaged machines,
not as a security control; the model and headers you enforce are on the request
itself. If you serve ANTHROPIC_CUSTOM_HEADERS in env, a repository can't
add a line of its own, but your value also replaces the custom headers
developers set in their own settings.
Treat the header as sensitive, for example in access logs. It is a plain SHA-256
with no secret key, and it also covers env entries added by a managed
settings file or MDM profile on the machine, so anyone who sees it and knows the
rest of the policy can test guesses at a short or human-chosen value there, such
as a password in a proxy URL. A long random secret can't be found that way.
A client that reaches you through ANTHROPIC_BASE_URL instead of /login
(other than Claude Desktop in gateway mode) never reads your
/managed/settings. For those machines, set
CLAUDE_CODE_GATEWAY_HINT_HEADERS and ANTHROPIC_BASE_URL together in the
managed settings they do take, such as a managed settings file or MDM profile.
Otherwise the developer's own settings, or those of a repository they have
trusted, decide which host receives the checksum. If those machines take
server-managed settings from Anthropic, a session that starts from its saved
copy leaves out managedMcpServers and env entries such as proxy,
certificate, endpoint, credential and custom-header variables until its first
fetch answers, and its checksum covers only what is left: accept that value too.
Models — optional
GET /v1/models (bearer)
Anthropic models-list shape: {"data":[{"id","display_name"},...]}. Use
Anthropic-style IDs (claude-{family}-{major}-{minor}) — the client's
model-family logic keys on that shape. The client only calls this when
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY is set on the client, which you
can push via the env block in /managed/settings. Return 404 to fall
back to the client's built-in list.
Telemetry — optional
POST /v1/metrics, /v1/logs, /v1/traces (bearer)
OTLP/HTTP (protobuf or JSON). When connected to a gateway the client sends
telemetry here and ignores OTEL_EXPORTER_OTLP_* env vars, with one
exception: when your own /managed/settings document names an OTLP endpoint
on another host (https, or http to loopback, at a collector's
…/v1/<signal> path) and nothing has overridden it, the
client exports there as an ordinary managed install (set the protocol and
headers in the same document; where it does not, the developer's apply) and
never sends the gateway bearer to it. Return 200
whether you forward or discard — 404 makes the client's exporter log an
error on every flush.
Errors
OAuth endpoints use {"error":"...","error_description":"..."}
(RFC 6749/8628). Bearer-authenticated endpoints use the Anthropic envelope so
the SDK surfaces the message to the user:
{"type":"error","error":{"type":"authentication_error","message":"..."}}
| HTTP | error.type | Use for |
|---|---|---|
| 400 | invalid_request_error |
Denied model, malformed body, policy violation |
| 401 | authentication_error |
Missing/expired/invalid bearer; client prompts re-login. Send x-should-retry: false with it for a revoked or expired bearer so the prompt is immediate; without the header the client retries with backoff for about three minutes first |
| 403 | permission_error |
Authenticated but not allowed |
| 413 | request_too_large |
Body over your cap |
| 429 | rate_limit_error |
Throttling; include Retry-After |
| 429 | billing_error |
The user's own cap on your gateway, or a budget their group shares, is reached; see Usage-limit headers below |
| 501 | not_supported |
Endpoint not available on this backend. Send x-should-retry: false with it; without the header the client asks once more, about half a second later, before it falls back |
| 529 | overloaded_error |
Upstream at capacity; client backs off and retries |
| 5xx | api_error |
Anything else |
Usage-limit headers — optional
If you enforce a per-user spend or usage cap, report the caller's standing
against it on each successful POST /v1/messages response and Claude Code
(2.1.225 and later, when signed in to a gateway) shows its usual "You've used
NN% of your usage credits · resets …" notice past 75% and again past 95%.
These are the same anthropic-ratelimit-unified-* headers api.anthropic.com
sends its subscribers, so strip the upstream's own anthropic-ratelimit-*
response headers first — otherwise your org-wide quota reaches users as if it
were theirs. Send none of these for a user with no cap.
| Header | Value |
|---|---|
anthropic-ratelimit-unified-status |
allowed, or allowed_warning once past a threshold |
anthropic-ratelimit-unified-representative-claim |
overage — the window-agnostic claim; 5h/7d mean rolling 5-hour/7-day windows the client does time math on, so don't borrow them for a calendar budget |
anthropic-ratelimit-unified-overage-status |
Same value as -status |
anthropic-ratelimit-unified-overage-utilization |
Fraction of the cap used, two decimals, kept below 1 while you're still allowing requests (0.82) |
anthropic-ratelimit-unified-overage-surpassed-threshold |
0.75 or 0.95 once utilization passes it — this header is what triggers the client's notice; omit it below 75% |
anthropic-ratelimit-unified-reset, -overage-reset |
When the cap resets, Unix seconds |
When the cap is reached, reject POST /v1/messages before proxying:
HTTP/1.1 429
retry-after: 37800
x-should-retry: false
anthropic-ratelimit-unified-status: rejected
anthropic-ratelimit-unified-reset: 1786147200
anthropic-ratelimit-unified-overage-reset: 1786147200
anthropic-ratelimit-unified-overage-utilization: 1
anthropic-ratelimit-unified-overage-surpassed-threshold: 1
anthropic-ratelimit-unified-overage-period: daily
anthropic-ratelimit-unified-overage-disabled-reason: org_spend_cap_reached
{"type":"error","error":{"type":"billing_error","message":"spend limit reached · resets Aug 8 · request an increase at https://go.corp.example.com/claude-limits"}}
Leave representative-claim and overage-status off the 429. With them the
client composes its own "You've hit your limit" line and drops your message;
without them it prints error.message as-is (older clients too, behind a
generic "API Error" prefix), so put when the cap resets and what the user
should do next in that one sentence. retry-after is seconds until the
reset; x-should-retry: false keeps the SDK from retrying into the block. If
you can't read your counter and choose to fail closed, send the 429 with
x-should-retry: false,
anthropic-ratelimit-unified-overage-disabled-reason: fetch_error, and a
message, nothing else. This gateway sends exactly the shapes above for caps
set through its admin API (overage-period is daily, weekly, or
monthly); when several caps apply it describes the fullest one, or once
blocked the one that resets last. When what ran out is a budget the user's
whole group shares, it sends the monthly shape plus
anthropic-ratelimit-unified-overage-scope: group_pool, which tells the
client that the user's own cap is not what blocked them.
To show the user dollars as well ("$271.40 / $500.00 spent"), also answer
GET /api/oauth/usage, the path claude.ai serves Claude Code's usage data on,
for the bearer's own cap. Newer Claude Code clients call it when signed in to
a gateway and add the amounts to /usage and the status line; on a 404 or
any other error they show the percent alone, and older clients never call it.
Put the cap the headers describe in extra_usage and one limits row per cap
naming its period, with is_active on the row the dollars belong to.
monthly_limit and used_credits are cents and must be numbers (the field
is named monthly_limit whatever the period); utilization and percent
are whole percents from 0 to 100 (above 100 once over), not the fraction the
headers use; resets_at is an ISO 8601 UTC time, the same instant as that
cap's anthropic-ratelimit-unified-overage-reset header, since clients pair
the dollars with the percent only when the two agree to the second. A user
with no cap gets "limits": [] and, in extra_usage, their spend in cents
for the current UTC month (used_credits), day (daily) and week from Monday
(weekly). monthly_limit and utilization are null: 0 would be a $0 cap.
daily is {"limit": null, "used_credits": 1240, "utilization": null}, and
weekly the same. Clients show all three amounts, or none if daily or
weekly is missing; older clients read this as {"limits": []}.
GET /api/oauth/usage
Authorization: Bearer <access_token>
HTTP/1.1 200
cache-control: no-store
{"extra_usage": {"is_enabled": true, "monthly_limit": 50000, "used_credits": 27140, "utilization": 54, "currency": "USD"},
"limits": [{"kind": "spend", "group": "monthly", "percent": 54, "resets_at": "2026-10-01T00:00:00.000Z", "severity": "normal", "is_active": true}]}
Billing group — optional
A request may say which of the developer's groups it is for, in the Anthropic
API's request tags: "tags": {"<name>": "<group>"} in the body of
POST /v1/messages. <name> is what the gateway's admin set as
admin.billing_group_tag. With it set, this gateway writes the group in its
audit log if the bearer token lists it, and takes a signed-in developer's tags
and their anthropic-beta value out before any upstream. The tag changes
nothing else about the request.
If your token is a JWT whose payload has "billing_group_tag": "<name>",
Claude Code puts the developer's attributionProject setting under that key
in tags on each Messages request. Add the claim only if your gateway
removes tags before any upstream.
Bearer token
The client stores your access_token, sends it, and refreshes it before
expires_in. If it is a JWT, the client also reads some of its claims without
verifying them, such as exp, sub and billing_group_tag. Encode the
user's identity and groups in the token (or in server-side state keyed by it)
so you can apply per-user RBAC at /v1/messages and per-group policy at
/managed/settings. The same token must work across every
bearer-authenticated endpoint.
TLS
https:// is required; http:// is accepted only for loopback during
development. The client pins the SHA-256 fingerprint of your TLS leaf
certificate per-hostname after the user confirms it on first connect. The
device authorization, token, refresh, revocation, managed-settings and usage
requests then fail when the certificate presented is not the pinned one (not
checked when the request goes through an HTTPS proxy), so serve the same leaf
certificate from every node behind the hostname. After a rotation, running
sessions can no longer refresh and the next launch starts signed out, until
the user runs /login and accepts the new certificate.
Client guarantees
- OAuth endpoint paths come from your discovery document; the client uses the default paths only when it can't use yours (see Discovery).
- Fixed-path endpoints are resolved against
{base}, never a redirect. - Every request body carries
Content-Length. - The OTLP exporter is locked to
{base}/v1/{signal}regardless of the user's environment; only your own/managed/settingsdocument can name a different collector, and the gateway bearer is never sent to it. 404from/v1/modelsor/managed/settingsis a clean "not implemented", with no retry storm.
Proxying to Bedrock, Vertex, or Foundry
Proxying to api.anthropic.com is pass-through. Proxying to a cloud
provider's Claude endpoint needs translation:
- Model IDs. The client sends Anthropic-style IDs like
claude-sonnet-4-5; translate to the upstream's form (Bedrock model ID or inference-profile ARN; Vertex@-versioned ID), or advertise upstream-native IDs from/v1/models. anthropic-beta. Bedrock rejects some betas in the header; move them into the request body as"anthropic_beta": [...]. Vertex and Foundry accept the header.- Request tags. Bedrock, Bedrock Mantle and Vertex reject the Anthropic
API's top-level
tagsbody field and its beta value,${REQUEST_TAGS_BETA}. Leave both out before those upstreams: they label usage and do not change the reply. - Streaming. Bedrock's native stream is AWS binary event-stream, not SSE;
decode and re-emit Anthropic-shaped
text/event-stream. The provider SDKs handle this, but their stream iterators drop the upstream'spingevents (and Bedrock sends none) — emit your ownevent: pingduring silent gaps so long thinking pauses don't trip client or proxy idle timeouts. count_tokens. Answer it with Bedrock'sCountTokens(an invoke body: nomodel, amax_tokensabove any thinking budget, no emptytools, and of the betas only those Claude Code sends Bedrock on a count, such asclaude-code-20250219) as{"input_tokens": N}. If that fails, or the model is an application inference profile (CountTokenstakes foundation-model ids only), return501 not_supported. A Claude Code session that holds a gateway credential (signed in with/login, or started withCLAUDE_CODE_USE_GATEWAY, as Claude Desktop does under yourcodepolicy) then counts by sending the prompt as a normal, billed model request with minimal output. That request goes to Haiku, or, in a session that reads your/managed/settings, to the session's model whenavailableModelsthere leaves Haiku out.ANTHROPIC_SMALL_FAST_MODELorANTHROPIC_DEFAULT_HAIKU_MODELon the client picks another model. A client that only pointsANTHROPIC_BASE_URLat the gateway estimates locally.- Headers. Forward
content-type,accept,accept-encoding,anthropic-version,anthropic-beta,user-agent, andx-stainless-*; strip the client'sAuthorizationand apply the upstream's own credentials. On the response, strip hop-by-hop headers (content-encoding,content-length,transfer-encoding,connection). - Errors. Upstream error messages can carry your cloud account
IDs/ARNs/project IDs — log them for the operator and return a generic
message, keeping
error.type. The exception is a 400/413 in Anthropic's own error envelope (e.g.prompt is too long: …): relay thaterror.message, the client's recovery (auto-compact etc.) keys on it. A second exception is Bedrock's 400 whose whole message isInput is too long.: send exactly that aserror.message; the client's recovery (drop older images, then compact) matches the whole message. Send that same sentence for Vertex's size 400, e.g.The request size (30037042 bytes) exceeds 30.000MB limit.(also wordedThe message size …).
References
RFC 6749 (OAuth 2.0), RFC 8414 (AS metadata), RFC 8628 (device grant), Anthropic Messages API, Claude Code settings reference, OTLP spec.