Claude API Key Rotation Automation Script Guide

Key rotation is the process of retiring an active API key on a schedule and replacing it with a new one before the old one is disabled, without breaking anything in production. If you're searching for a rotation script, you almost certainly want two things: a way to generate and swap keys without downtime, and a way to make that repeatable so it isn't a manual fire drill every quarter.

This article walks through a practical automation pattern for rotating credentials used to call Claude, whether you're using Anthropic's API directly or a proxy layer like SubToAPI that issues its own application keys (sub_live_...). The mechanics are the same in both cases: generate new, deploy new, verify new, revoke old.

Why rotate Claude API keys at all

Static keys that never expire are a liability. If a key leaks into a git history, a client-side bundle, a CI log, or a support ticket, it stays valid until someone notices and manually revokes it — which can be weeks. Rotation limits the blast radius: even a leaked key becomes useless after your next scheduled rotation, and a documented rotation process makes revocation during an incident fast instead of improvised.

Common triggers for rotation:

• Scheduled — every 30, 60, or 90 days regardless of events
• Employee offboarding — anyone with key access leaves the team
• Suspected leak — key shows up in a log, repo, or error report
• Provider-side incident — you're asked to rotate as a precaution

The core rotation pattern

A safe rotation script never deletes the old key before the new one is confirmed working. The sequence is always:

1. Create a new key
2. Store it in your secrets manager under a new version
3. Deploy the new key to your services
4. Run a smoke test against the live API using the new key
5. Only after the smoke test passes, revoke the old key

Skipping step 4 is how rotations turn into outages — you revoke the old key, the new one has a typo or wrong scope, and requests start failing with 401s before anyone notices.

Example rotation script

Here's a shell script that automates the flow using a generic secrets store and a Claude-compatible API. Adapt the create-key and revoke-key calls to whatever key management your provider exposes — direct Anthropic console access is manual today, so this pattern fits best with a proxy or gateway that exposes key management via API.

#!/usr/bin/env bash
set -euo pipefail

SECRET_NAME="claude-api-key"
API_BASE="https://api.subtoapi.app/v1"
OLD_KEY=$(vault read -field=key secret/$SECRET_NAME)

# 1. Create a new key via your provider's key management API
NEW_KEY=$(curl -s -X POST "$API_BASE/keys" \
  -H "Authorization: Bearer $SUBTOAPI_ADMIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name": "rotated-'"$(date +%Y%m%d)"'"}' | jq -r '.key')

if [[ -z "$NEW_KEY" || "$NEW_KEY" == "null" ]]; then
  echo "Key creation failed, aborting rotation" >&2
  exit 1
fi

# 2. Store the new key as a new secret version
vault write secret/$SECRET_NAME key="$NEW_KEY" previous="$OLD_KEY"

# 3. Smoke test the new key against a live endpoint
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "$API_BASE/messages" \
  -H "Authorization: Bearer $NEW_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-7-sonnet","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}')

if [[ "$STATUS" != "200" ]]; then
  echo "Smoke test failed with status $STATUS, keeping old key active" >&2
  exit 1
fi

# 4. Trigger a rolling redeploy so services pick up the new secret version
kubectl rollout restart deployment/claude-worker

# 5. Wait for rollout to finish before touching the old key
kubectl rollout status deployment/claude-worker --timeout=120s

# 6. Revoke the old key only after the new one is confirmed live
curl -s -X DELETE "$API_BASE/keys/$OLD_KEY" \
  -H "Authorization: Bearer $SUBTOAPI_ADMIN_TOKEN"

echo "Rotation complete."

Run this from a cron job or a scheduled CI pipeline (GitHub Actions schedule: trigger works well) rather than a laptop, so rotation happens even when someone is on vacation.

Building in a grace period

Instead of revoking the old key immediately after the smoke test, many teams keep it valid for 24–48 hours as a rollback buffer. This catches cases where the smoke test passes but a low-traffic service that only gets used once a day hasn't picked up the new secret yet. Change step 6 above to schedule a delayed revocation job rather than an immediate delete call, and log both key IDs with timestamps so you know exactly when the grace period ends.

Handling multiple environments

If you run staging, production, and preview environments off separate keys, rotate them independently and stagger the schedule — don't rotate all environments on the same day. A staging rotation failure should never block or delay a production rotation, and vice versa. Namespace your secrets clearly (claude-api-key-prod, claude-api-key-staging) so the script can be parameterized with an environment argument instead of duplicated.

Where SubToAPI fits

If you're rotating keys because you're worried about a shared team credential leaking, it's worth checking whether the root problem is that everyone on the team is using the same Claude key. SubToAPI turns your existing Claude access into per-application API keys — each service, environment, or team member gets its own sub_live_... key with its own usage tracking, so a single leak doesn't mean rotating credentials for your entire org. Key creation and revocation happen through the dashboard, and the quickstart covers wiring a new key into an existing integration in a few minutes, which is most of what a rotation script needs to automate.

Testing your rotation script safely

Before wiring this into production cron, run it against a staging key with a fake "old key" that you don't care about breaking. Confirm:

• The script exits non-zero on any failed step (never silently continues)
• The smoke test actually exercises the endpoints your app uses, including streaming if you rely on it
• Old keys are logged, not just deleted, so you have an audit trail
• Alerts fire (Slack, PagerDuty, email) on rotation failure, not just success

questions

How often should I rotate a Claude API key? Every 60–90 days for routine hygiene, plus immediately on suspected leak or team member offboarding. Shorter cycles (30 days) make sense for high-traffic production keys.

Can I rotate a key without any downtime? Yes, if you always create and verify the new key before revoking the old one, and use a grace period rather than an immediate delete. The script above follows this pattern.

Does Anthropic support automated key rotation natively? Direct Anthropic console keys are managed manually today. Gateways like SubToAPI expose key creation and revocation through an API, which is what makes scripted rotation practical — see /docs for the current endpoints.