Provider keys need periodic rotation. This guide will walk through the add-validate-delete flow that rotates a BYOK credential without dropping live traffic. The whole approach rests on one property: the old credential keeps serving traffic until you delete it. So if you add the new key first, confirm it works, and only then remove the old one, there is never a window in which the environment has no valid credential for the provider.

​
Before you start

  • Rotation is a control-plane operation on , gated at projects.write (member or above). Use your dashboard session, a secret-key-free management key, or the dashboard UI.
  • Provider secrets are envelope-encrypted, bound to org:project:credential, and only the gateway can decrypt them. After creation the plaintext is never re-readable — you can validate, rotate, or delete a credential, but you cannot read it back. Only a last-4 key_fingerprint is ever shown.
  • The gateway reads credentials from its config snapshot, so a change propagates on the config-dirty push (and, at worst, within the snapshot TTL) — no gateway restart.

​
1. Add the new credential

Create the replacement key. Roadie makes a live validation call to the provider on save and records the result, so an invalid key is rejected up front and never quietly stored as usable.
  • environment_id scopes the credential to one environment. Omit it to make the credential apply to every environment in the project.
  • The response carries the credential id, its status (valid / invalid / unverified / revoked_by_provider), and the key_fingerprint — never the key itself.
Because you are adding the new key before removing the old one, the old (still-valid) credential continues to serve every request in the meantime. There is no gap.

​
2. Confirm traffic succeeds

Send real traffic (or a smoke-test request) and confirm it resolves cleanly. If you want to re-check a stored credential’s health at any time without deleting it, call the validate route — it decrypts the stored key, makes a fresh provider call, and updates the recorded status:
A valid status means the gateway can serve traffic on the new key.

​
3. Delete the old credential

Once the new key is confirmed, remove the old one. The change publishes config-dirty for every affected environment, so the gateway stops offering the deleted credential on the next snapshot load.
That completes the rotation. Every step is recorded in the audit log with masked, non-secret fields only.

​
Rolling back

If the new key turns out to be bad, the rollback is trivial: delete the new credential instead of the old one. The old credential is still in place and serving traffic, so removing the failed new key returns you to exactly where you started.

​
Multiple keys per provider

If you maintain more than one credential for the same provider, an alias target can pin a specific credentialId; otherwise the environment’s default credential for that provider is used. A credential a target cannot use is simply skipped, so an alias still routes as long as one eligible target remains.

​
What is protected, and what never leaks

  • The provider secret is envelope-encrypted before it touches the database — a per-secret AES-256-GCM data key, itself wrapped by the master key (a local master key in development, AWS KMS in production).
  • The ciphertext is bound to org:project:credential as additional authenticated data, so a database row copied under another id or tenant fails to decrypt.
  • Under production KMS, only the gateway’s role can call Decrypt at all.
  • Provider keys never appear in responses, request logs, usage records, or error messages. If a provider returns an error, the gateway maps it to a provider_error with a safe message — never the provider’s raw body.

Providers & BYOK

How credentials are stored, selected, and protected.

Security best practices

Key handling, restrictions, and least privilege.