CLAUDE_BG_SESSION_CREDENTIAL
Updated by Alex Sorokoletov
CLAUDE_BG_SESSION_CREDENTIAL is a Claude Code environment variable: Supplies the credential for a background session; it is read only when a gating check passes and is used only if the value validates, otherwise ignored. Added between v2.1.321 and v2.1.323 and still present in v2.1.324. It is not in the official reference.
| Status | Present in v2.1.324 |
|---|---|
| Added | Added between v2.1.321 and v2.1.323 |
| Category | Authentication |
| Official docs | Not listed |
How to set it
For one session, export it in the shell that starts Claude Code:
export CLAUDE_BG_SESSION_CREDENTIAL=<value>
claudeTo apply it to every session, add it to the env object of a settings file:
// ~/.claude/settings.json
{
"env": {
"CLAUDE_BG_SESSION_CREDENTIAL": "<value>"
}
}Related variables
CLAUDE_CODE_SESSION_ACCESS_TOKEN: Session-scoped access token.CLAUDE_SESSION_INGRESS_TOKEN_FILE: Path to the file the session ingress token is read from; a well-known path is used when unset.ANTHROPIC_API_KEY: Primary API key for Claude API.ANTHROPIC_AUTH_TOKEN: Alternative bearer token; takes priority over API key.CLAUDE_AI_AUTHORIZE_URL: Authorization URL endpoint.CLAUDE_BG_AUTH_SNAPSHOT_PATH: Path for snapshotting background session auth credentials to disk.CLAUDE_BG_CLAIM_AUTH: Held the claim authentication token for a background spare session's claim gate, used as a fallback when the socket tokens file supplied none; read until v2.1.309.CLAUDE_BG_PTY_AUTH: Carries the authentication token for the background PTY host's data gate; it is consumed and removed at startup, and the socket tokens file takes precedence.
Frequently asked questions
What does CLAUDE_BG_SESSION_CREDENTIAL do?
Supplies the credential for a background session; it is read only when a gating check passes and is used only if the value validates, otherwise ignored.
Which Claude Code version has CLAUDE_BG_SESSION_CREDENTIAL?
Added between v2.1.321 and v2.1.323 and still present in v2.1.324.
How do I set CLAUDE_BG_SESSION_CREDENTIAL?
Export it before starting Claude Code (export CLAUDE_BG_SESSION_CREDENTIAL=value), or add it to the "env" object in ~/.claude/settings.json to apply it to every session.
All variables, searchable: Claude Code environment variables.