Skip to main content

Credential rotation

You have two kinds of credentials: API keys (which authenticate requests) and signing secrets (which sign requests, responses, and webhooks). Both can be rotated with zero downtime, because the platform supports multiple active credentials at once. All rotation is performed from the Orchestr Dashboard.

Rotate on a regular schedule, and immediately if a credential may have been exposed.

Why rotation is seamless​

The signing design makes secret rotation safe by construction:

  • Verifying your requests: Orchestr checks your request signature against every active signing secret and accepts it if any of them matches.
  • Signing its responses and webhooks: Orchestr signs with every active signing secret, emitting one v1 per secret in the X-Signature header (t=…, v1=…, v1=…).

So during the window where both an old and a new secret are active, signatures made with either one are valid in both directions. The same multiplicity applies to API keys: several can be active simultaneously.

Rotating a signing secret​

You can have up to 5 active signing secrets at once. To rotate with no downtime:

  1. Create a new signing secret in the Dashboard. Copy its value (shown once) into your secrets store. Now two secrets are active.
  2. Switch signing of your outbound requests to the new secret. Because Orchestr still accepts the old one, in-flight and not-yet-deployed instances keep working.
  3. Update verification. Your response/webhook verifier should already accept any v1 — during the overlap Orchestr sends a v1 for both secrets, so no change is needed if you followed the verification pattern. Confirm it does.
  4. Wait out the overlap. Allow time for all your instances to deploy and for any in-flight webhook retries (which can span up to ~27 hours; see Retries) to drain.
  5. Revoke the old secret in the Dashboard. Orchestr stops accepting and emitting signatures for it immediately.
Keep verification rotation-ready permanently

If your webhook/response verifier always loops over all v1 values and accepts on the first match, you never have to touch verification code to rotate a secret — only the signing side changes.

Rotating an API key​

You can hold up to 10 secret and 20 publishable keys. To rotate a secret key:

  1. Create a new secret key in the Dashboard and store it securely.
  2. Deploy your application configured to send the new key in the Authorization header.
  3. Verify traffic is authenticating with the new key (the Dashboard shows each key's last-used time and last four characters).
  4. Revoke the old key. Revocation takes effect immediately — any request still using it will get 401 unauthenticated.

Because a request must be both authenticated and signed, you can rotate API keys and signing secrets independently.

If a credential is compromised​

Prioritise stopping the leak over avoiding downtime:

  1. Revoke the affected credential immediately in the Dashboard. A revoked API key or signing secret stops working at once.
  2. Create a replacement and deploy it.
  3. Investigate: use request_ids and the Dashboard's last-used data to scope what may have been accessed, and reconcile recent activity via the search endpoints.

A brief failure of in-flight requests is an acceptable price for closing an active exposure.

Best practices​

  • Store keys and signing secrets in a managed secrets store, never in source control or client code.
  • Rotate on a schedule (e.g. quarterly) in addition to incident-driven rotation.
  • Keep overlap windows long enough to cover your deploy time and the webhook retry window.
  • Use separate credentials per environment — Sandbox and Live credentials are already isolated.