Api Key Polished

Configure dynamic API key generation through custom scripts for environments with rotating credentials or temporary access tokens.

When to Use This Setting

Apply this setting when you need to:

• Integrate Claude Code with credential management systems that issue short-lived API tokens
• Automate API key rotation without manual intervention during active coding sessions
• Support SSO or vault-based authentication workflows that require programmatic token retrieval

Consider alternatives when:

• You have a static, long-lived Anthropic API key that does not require rotation
• Your authentication is handled entirely through cloud provider IAM (Bedrock or Vertex)

Quick Start

Configuration

Copy
name: api-key-polished
type: setting
category: authentication

Example Application

Copy
claude setting:apply api-key-polished

Example Output

Setting applied successfully. Configuration changes:
- apiKeyHelper: /bin/generate_temp_api_key.sh
- CLAUDE_CODE_API_KEY_HELPER_TTL_MS: 3600000
- Key refresh: automatic every 60 minutes

Core Concepts

Dynamic Key Management Overview

Aspect	Details
Mechanism	External script generates fresh tokens
TTL	Configurable time-to-live in milliseconds
Script Format	Any executable returning a key to stdout
Refresh	Automatic on TTL expiry before next request
Fallback	Cached key used until refresh succeeds

Key Helper Architecture

┌──────────────┐     ┌──────────────────┐
│  Claude Code │     │  Key Helper      │
│              │     │  Script          │
│  On Request: │     │  ┌────────────┐  │
│  1. Check    │────>│  │ Vault/SSO  │  │
│     TTL      │     │  │ Provider   │  │
│  2. If       │     │  └─────┬──────┘  │
│     expired  │     │        │         │
│  3. Execute  │<────│  Fresh API Key   │
│     helper   │     │  (stdout)        │
│  4. Cache    │     └──────────────────┘
│     new key  │
└──────────────┘

Configuration

Parameter	Type	Default	Description
apiKeyHelper	string	none	Path to executable script that outputs API key
CLAUDE_CODE_API_KEY_HELPER_TTL_MS	string	"3600000"	Cache duration in ms before re-running helper
API_KEY_HELPER_TIMEOUT_MS	string	"10000"	Max time to wait for helper script execution
API_KEY_HELPER_RETRY_COUNT	string	"3"	Number of retry attempts on helper failure
API_KEY_HELPER_SHELL	string	"/bin/bash"	Shell used to execute the helper script

Best Practices

1. Keep Helper Scripts Idempotent - The helper script should produce a valid key on every invocation without side effects. Avoid scripts that modify state or depend on previous runs, as Claude Code may invoke the helper at unpredictable intervals.

2. Set TTL Below Token Expiry - Configure the TTL to be at least 10-15 minutes shorter than the actual token lifetime. This buffer prevents edge cases where a cached token expires between validation and the actual API call.

3. Handle Script Failures Gracefully - Ensure your helper script returns a non-zero exit code on failure. Claude Code uses the exit code to determine whether to retry or fall back to the cached key, and silent failures cause cryptic authentication errors.

4. Log Key Refresh Events - Add logging within your helper script to track when keys are refreshed. This creates an audit trail and helps diagnose authentication issues without exposing the actual key values.

5. Secure the Helper Script - Set restrictive file permissions (chmod 700) on the helper script and store it outside the project directory. This prevents other users or processes from reading the script that has access to your credential management system.

Common Issues

1. Helper script not found or not executable - Verify the script path is absolute, the file exists, and it has execute permissions. Relative paths resolve against the Claude Code working directory, which may change between sessions.

2. TTL too short causing excessive refreshes - If the helper script calls a remote vault, frequent refreshes add latency to every Claude Code interaction. Set TTL to at least 30 minutes unless your security policy mandates shorter intervals.

3. Script outputs extra whitespace or newlines - The helper must output only the API key with no trailing newline or whitespace. Use echo -n or printf in your script to avoid invisible characters that invalidate the key.