Skip to the content

Give Claude Code a per-developer gateway key

Give each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Have Central Lite issue each developer their own gateway key, let Claude Code fetch it from agentgarmd through apiKeyHelper, and route its calls through the proxy to your organisation's gateway under that key; a revoked or expired key then stops working on every machine, and a claude.ai login is never routed.

1. Know why a subscription login is refused

AgentGarm never routes, stores or reuses subscription credentials. When Claude Code runs through agentgarm run, its model calls go to the proxy, and a call carrying a claude.ai login (or a ChatGPT-plan one) is refused with 403 before anything is forwarded: “AgentGarm does not route subscription (claude.ai or ChatGPT plan) credentials. Use an API key or your gateway-issued key (apiKeyHelper).” The proxy raises a bypass alert naming only the credential's class, and never logs or keeps the token. Tunnels to claude.ai and chatgpt.com are refused too.

API keys and gateway keys pass through untouched. A gateway key also tells AgentGarm which developer made each call.

See also

Check that protection is on

See whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.

2. Bind the developer to a principal in Central Lite

Gateway keys come from Central Lite and reach only machines enrolled in it, which takes a root install. On the Central Lite host, add a principal for the developer and bind their login name to it, on every host or one; each change publishes a new version of the identity registry. garm-central identity show lists principals with their ids. If your identity provider provisions people through SCIM, the developer's principal is already there, and their login name too if you bind logins from SCIM (Provision and remove people with SCIM).

sudo agentgarm node enrol     # reads the one-time enrolment token from stdin
garm-central identity principal add --kind human --name "Ada Lovelace"
garm-central identity show
garm-central identity bind --principal <principal id> --username ada

See also

Give every agent an owner and an identity

Register each person and agent in Central Lite's identity registry, issue and revoke gateway keys, and see which identity every task belongs to.

3. Issue the key

garm-central identity key issue mints a key for an active principal (agk_ and 64 hex digits), seals it in Central Lite's keystore and never prints it. It expires after 2,160 hours by default, 8,784 at most. Central Lite delivers it over the control channel to each enrolled machine the principal is bound to, where agentgarmd seals it in its own keystore, bound to the credential and the principal.

On the developer's machine, agentgarm identity lists the gateway keys held for you, by credential, with their state; never the key itself.

garm-central identity key issue --principal <principal id>
agentgarm identity

Checked by the walk: this command ran as written on a Linux node enrolled in Central Lite.

4. Point apiKeyHelper at agentgarm

agentgarm identity api-key prints your newest usable gateway key on stdout and nothing else, and exits non-zero when none is held. agentgarmd releases it only to the account its principal is bound to, never a revoked or expired one, and logs the release by credential id only. It answers inside a governed task, since Claude Code itself asks.

Set Claude Code's apiKeyHelper setting to that command, "apiKeyHelper": "agentgarm identity api-key", in the managed settings your organisation deploys (/etc/claude-code/ on Linux, /Library/Application Support/ClaudeCode/ on macOS). With apiKeyHelper set, Claude Code skips its server-managed settings fetch, so deliver Claude Code's managed settings by file or MDM.

A managed apiKeyHelper applies to every Claude Code launch on the machine, not only those through agentgarm run, and a launch outside it sends the gateway key to whatever endpoint Claude Code would use otherwise. Roll the setting out only once every launch goes through the gateway route below.

agentgarm identity api-key

5. Run Claude Code and check the route

Start Claude Code with agentgarm run, which points its model traffic at the proxy. The proxy matches the key to your credential and principal, records them on each model call, and forwards the key unchanged; the key itself is never logged or stored. AgentGarm does not exchange it for a provider key, so it works only when the session's anthropic route points at your organisation's gateway, which accepts these keys (agentgarm-session --upstream anthropic=https://<your gateway>). It does not work against api.anthropic.com, the route's default.

agentgarm status shows whether the session's proxy answers and each task's assurance level, and agentgarm identity your spend over 30 days by credential.

agentgarm run -- claude
agentgarm status
agentgarm identity

See also

See what each task cost

Route an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model.

6. Rotate or revoke a key

--rotates issues a new key and revokes the old credential in the same action. To end a key, revoke its credential: Central Lite puts it on the signed revocation list and erases its sealed key, and each machine erases its copy once it receives the list from Central Lite. Within a minute after that, its proxy refuses any call that presents the key, with 403 and “AgentGarm: this gateway key is revoked or no longer usable; get a current one (agentgarm identity api-key)”, and forwards nothing. An expired key is refused the same way.

When a developer leaves and your identity provider deactivates them through SCIM, their principal is suspended and the registry published at once, which ends every key AgentGarm issued them the same way, with no command here (offboard someone).

garm-central identity key issue --principal <principal id> --rotates <old credential id>
garm-central identity credential revoke <credential id> --reason "laptop lost"