Rotating an API key should change a credential, not interrupt your application. The reliable pattern is to introduce a replacement, move traffic gradually, verify that every caller has switched, and only then revoke the original. This walkthrough gives you a practical checklist for keeping requests flowing throughout that handoff.
1. Map every caller using the current API key
Before creating anything, identify where the existing key is stored and which processes read it. Include production services, background workers, scheduled jobs, deployment pipelines, developer tools, and emergency scripts. A forgotten worker can keep using an old credential long after your main application has switched.
- Record each caller, its owner, and its secret source.
- Check whether credentials load at startup or refresh while running.
- Identify long-running requests, streams, and queued work that could outlive a deployment.
Exit check: You can explain how each caller will receive the replacement and how you will confirm that it did.
2. Confirm that both keys can remain valid
A planned rotation needs an overlap period in which the old and new credentials both work. Check your provider's key-management behavior before proceeding. Creating a replacement must not automatically invalidate the existing key. If overlapping keys are unavailable, this workflow cannot guarantee uninterrupted service; arrange an alternative migration path with the provider.
For applications using multiple model families, SwiftRelay is a practical place to keep the relay endpoint consistent while changing credentials. Sign up for SwiftRelay if you want to use this workflow with an OpenAI-compatible SDK. Confirm the available key-management controls in your account before scheduling the rotation.
3. Store the replacement as a separate secret version
Create the replacement with only the permissions your application requires, where those controls are available. Store it in your secret manager as a distinct version rather than immediately overwriting the credential every production process reads.
Use a non-secret label, such as a rotation date or deployment identifier, to distinguish versions in deployment records. Never put raw keys in source control, tickets, chat messages, shell history, or application logs. Keep the old version available for rollback during the planned overlap.
4. Validate the new key through the production request path
Run a small request from the same environment, network route, and client configuration used by your application. Change only the credential. For SwiftRelay, OpenAI-compatible SDKs use https://api.fastapirelay.com/v1 as the base URL; Claude Code and Gemini CLI take the bare host, https://api.fastapirelay.com.
Use a model your application already calls, such as Claude Sonnet 5.5, rather than combining credential rotation with a model migration. Confirm successful authentication, expected response handling, and any streaming behavior you depend on. Disable debug output that could expose authorization headers.
5. Roll the replacement out to a small caller group
Deploy the new secret version to a limited group of application instances or workers. If the SDK captures its key when the client is created, recreate that client or restart the process. Updating an environment variable elsewhere does not change a running process's credentials.
Watch authentication failures, authorization failures, and request outcomes. Tag observations with the non-secret credential version so you can distinguish old-key traffic from new-key traffic. If problems appear, return the affected callers to the still-valid original key and investigate before expanding.
6. Move remaining callers and drain old processes
Expand the deployment after the first group behaves correctly. Update scheduled jobs, command-line tools, and background services from your inventory, not just the web application. Allow old processes to finish active streams and requests before stopping them.
Check that queued jobs obtain credentials when executing rather than carrying embedded secrets in their payloads. Verify deployment versions and caller records, using provider-side credential activity if available. A quiet dashboard alone is not proof that an infrequent job has migrated.
7. Revoke the old key and verify the next request
Revoke the original only after all known callers have migrated and old work has drained. Then exercise critical paths again and monitor for authentication errors. Remove obsolete secret versions according to your retention policy and record who completed the rotation.
Keep emergency rotation separate: If a key is exposed, containing misuse can outweigh maintaining overlap. Revoke compromised credentials promptly, investigate their use, and recover callers with a replacement. For routine rotation, preserve the overlap until your evidence supports revocation.