← All posts
Tutorial

Rotate a UnifyPort API Key Without Downtime

To rotate a UnifyPort API key without downtime, do not call the rotate endpoint first. POST /v1/api-keys/{key_id}/rotate invalidates the old key immediately. Instead, create a second active key, store its one-time secret, deploy it to every caller, verify it with GET /v1/workspace, and only then set the old key to inactive.

Key takeaways

  • The dedicated rotate endpoint is an immediate cutover: the old secret stops working as soon as rotation succeeds.
  • Zero-downtime replacement uses two keys briefly: create, deploy, verify, and deactivate.
  • A new or rotated full secret appears once under data.api_key; it cannot be retrieved later.
  • API key list responses expose key_prefix, not the full secret.
  • Use the immediate rotate endpoint for an urgent credential response or a coordinated maintenance cutover, not an ordinary rolling deployment.

Why the rotate endpoint can interrupt production

The Rotate API key reference defines a precise operation:

POST /v1/api-keys/{key_id}/rotate

It creates a fresh key record and returns the new secret once, but it also makes the old key invalid immediately. That behavior is useful when the old credential must stop authorizing requests now. It is risky when several web processes, queue workers, scheduled jobs, or regional deployments still read the old value.

A rolling deployment creates an overlap period by design. Some instances use the new configuration while others finish work with the previous configuration. An atomic credential cutover removes that overlap and can turn otherwise healthy requests into 401 invalid_api_key responses.

The general security objective is still regular authenticator management. NIST SP 800-53 includes changing or refreshing authenticators within its authenticator-management controls. The safe operational sequence, however, must follow the actual product contract: UnifyPort supports multiple API key records, creation returns a secret once, and the rotate operation invalidates its predecessor immediately.

The zero-downtime API key rotation runbook

1. Inventory every caller before changing a credential

List the places that send X-Api-Key to https://api.unifyport.ai: the public application, background workers, webhook-processing jobs that make reply calls, scheduled tasks, local production tools, and deployment health checks.

Do not confuse the API key with a webhook signing_secret. The API key authenticates your requests to UnifyPort. The signing secret verifies deliveries sent to your webhook. If you need to review that second secret path, the webhook HMAC and replay-protection guide explains it separately.

You can inspect key records with the List API keys endpoint:

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

The response provides each key’s id, name, key_prefix, and status. It deliberately does not reveal the complete secret.

2. Create a second active key

Use Create API key instead of rotate:

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

A successful 201 response returns the key metadata under data.key and the full new secret under data.api_key. Capture that value directly into your approved secret store. Do not print it in deployment logs, paste it into tickets, or expect the list endpoint to recover it later.

If the one-time value is lost before deployment, create another key and deactivate the unused record. Do not guess the secret from its prefix.

3. Prove the new key before deployment

Use the new secret for a read-only authentication check:

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

A successful response confirms that the new key resolves to the workspace. It does not prove every application instance has loaded it, so treat this as the first gate rather than the whole rollout test.

Next, update the secret reference used by your deployment and roll it through each caller. Keep the old key active during this phase. Record deployment versions or instance groups in your change log, but never record either secret value.

4. Verify the whole fleet uses the new credential

Check each application class, not just one HTTP process:

  • web and API instances have completed their rollout;
  • queue consumers have restarted or reloaded configuration;
  • scheduled jobs will read the new secret on their next run;
  • reply or send paths can make an authenticated request;
  • no emergency script depends on a copied old value.

Use application-side request outcomes and deployment state for this gate. The UnifyPort list endpoint shows key metadata and status; it does not document per-key last-used analytics. Do not invent certainty from data the endpoint does not return.

For teams beginning with the dashboard rather than the API, the dashboard and API key management announcement provides the surrounding workflow. This runbook adds the deployment ordering needed for a live system.

5. Deactivate the old key

After every caller is confirmed on the new secret, use the new key to deactivate the old record through Update API key status:

curl -X PATCH "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

The documented states are active and inactive. After deactivation, make one controlled request with the retired secret and confirm that it is rejected with 401 invalid_api_key. Do not send real business work as that test.

Finally, remove the old value from deployment configuration, local environment files, CI variables, and temporary migration material. Keep only non-secret metadata—key ID, name, status, change owner, and cutover time—in the operational record.

When to use immediate rotation instead

Use POST /v1/api-keys/{key_id}/rotate when immediate invalidation is the requirement, not something to avoid. Examples include a credential that may have been exposed or a maintenance window in which all callers can switch together.

The sequence is then different:

  1. stop or isolate callers that still hold the old key;
  2. call rotate from a controlled operator path;
  3. capture data.api_key once;
  4. update every secret consumer;
  5. restore traffic and verify authentication.

That path prioritizes revocation speed over continuous availability. If exposure is suspected, do not preserve overlap merely to keep requests flowing; follow your incident policy.

Limitations and trade-offs

A brief two-key overlap means both active credentials authorize the workspace during the rollout. Keep that interval as short as operationally practical and control who can access either secret. UnifyPort’s introduction states that X-Api-Key resolves to one workspace and grants access within it, so this is not a per-endpoint permission migration.

This runbook also does not rotate webhook signing secrets, provider login material, or imported sessions. Those have different consumers and failure modes. Credential replacement should be split by secret type rather than bundled into one untestable change.

FAQ

Does UnifyPort API key rotation have a grace period?

The documented rotate endpoint does not provide one. It invalidates the old key immediately. Create a second key first when you need an overlap window.

Can I retrieve a new API key again later?

No. The full value is returned once under data.api_key. Later list responses expose only metadata such as key_prefix and status.

How do I test the new key safely?

Call GET /v1/workspace with the new X-Api-Key. Then verify that every deployed caller has loaded the same secret before deactivating the old record.

Should I use rotate or create plus deactivate?

Use create plus deactivate for a normal rolling deployment. Use rotate when immediate invalidation is intentional and you have planned for the interruption or isolated all old-key callers.

Is a UnifyPort API key the same as signing_secret?

No. X-Api-Key authenticates calls to the REST API. signing_secret lets your receiver verify webhook HMAC-SHA256 signatures.

Next step

Open the Create API key reference, create the parallel production credential, and complete the five gates above before changing the old key’s status.

Sources

Checked August 17, 2026: