Ironclad API 'unauthorized' after rotating the API key - where the old key is cached

TL;DR

Ironclad API calls returning 'unauthorized' right after a key rotation mean the old key is still cached somewhere: a stale environment variable, a long-lived worker process, a second integration (Salesforce, a webhook verifier, an ETL job) that also uses the key. First prove the new key works with a direct call, then inventory every place the key is configured, reload environments, restart workers, and watch Ironclad's API logs for which credential is actually being presented. Rotate the key, then rotate every copy of it.

The query

Ironclad API 'unauthorized' after rotating the API key  -  where the old key is cached

Use this when

• Ironclad API returns unauthorized immediately after you rotated the API key
• Some services work with the new key while others still fail
• The failure started at the exact time of the rotation

Not for

• Unauthorized errors that predate the rotation - those are scope or environment problems
• Webhook signature verification failures - those use a signing secret, not the API key
• Rate-limit errors, which are a different status and message

Steps

1. Prove the new key works in isolation

Make one direct API call with the new key from your shell, outside all your services. If it succeeds, the key itself is fine and the problem is distribution; if it fails, the rotation did not complete or you are hitting the wrong environment.

curl -s -o /dev/null -w "%{http_code}" \
  -H "your auth header \
  https://example.com/api/v1/test

Expected output: a 200. Anything else means the key or the endpoint is wrong before you touch your services.

2. Inventory every place the key is configured

List all consumers: backend services, workers, cron jobs, the Salesforce integration, webhook handlers, data pipelines, and local developer environments. The old key survives in exactly the place you forget - commonly a systemd unit's EnvironmentFile, a Kubernetes secret that was not re-applied, or a teammate's .env. Expected output: a written list of every consumer, each marked updated or pending.

3. Reload configuration and restart long-lived processes

Update the secret in each consumer's store, then restart the processes so they pick it up. Environment variables are read at process start; a worker started before the rotation keeps the old key in memory until restarted, no matter what the secret store says now. Expected output: after restarts, each consumer's next API call succeeds.

4. Identify the failing caller from Ironclad's side

Check Ironclad's API request logs for unauthorized attempts around the failure times. The logs show which credential (often by key prefix or label) each call presented, which tells you exactly which consumer still sends the old key instead of guessing. Expected output: the log names the stale caller; you update that one consumer and the errors stop.

Tool compatibility

Ironclad public API with API-key authentication. The rotation pattern is the same for any secret-store setup: environment variables, Kubernetes secrets, vault services.

Variant phrasings

• Ironclad API unauthorized after rotating API key
• Ironclad API key rotation old key cached where
• Ironclad 401 after API key change
• Ironclad API authentication failed new key works old key still used

Why it happens

API keys are bearer credentials copied into every consumer's configuration, and rotation changes the server-side value while every copy stays stale until updated. Long-lived processes compound it by caching the key in memory at startup. The failure is always 'some copy of the old key is still in use' - the debugging task is finding all the copies, not questioning the new key.

Edge cases / pitfalls

• Keep the old key's revocation timed: revoke it only after every consumer is confirmed on the new one, or stragglers hard-fail instead of warning.
• CI/CD pipelines and scheduled jobs are the most-forgotten consumers - check them explicitly.
• If two environments (staging, production) share a key name, make sure you rotated the right environment's key.
• Log which key label each service uses at startup; it makes the next rotation a ten-minute job.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1-smUQRF7L7tXR4zu7JUUw