Skip to content
NovaVMS Manual

Rotate an API key

API keys authenticate machine integrations — recording exporters, alert consumers, ticketing bridges. Rotating a key is the way you limit blast radius when a key is exposed, when a contractor leaves, or when your compliance calendar says it is time. The goal of a rotation is no downtime for the integration: you issue a new key, push it to the consumer, verify traffic is flowing on the new key, and only then revoke the old one.

Service accounts and API keys are a D83 feature; the UI at /admin/service-accounts is the place you manage them. In v1 only admins and owners can issue or revoke API keys (D81, D83 — key material is governance).

Procedure

  1. Open Settings -> API Keys from the left nav (service accounts UI under /admin/service-accounts).
  2. Find the service account whose key you want to rotate and click it.
  1. Click + Create Key. Give the key a name and scope (the scope should match what the old key had — otherwise the integration will 403 on endpoints the old key could hit).
  2. The key is displayed once in a modal. Copy it into the integration’s secret store now. You cannot retrieve it later.
  1. Update the integration’s configuration to use the new key. Deploy / restart the integration.
  2. Wait for traffic to appear on the new key in the Last used column — the value updates within a minute of the first request.
  1. Click Revoke on the old key. Confirm the action. The old key fails all subsequent requests with 401.

The audit log records user.updated entries for key issuance and revocation with the actor’s user_id, the key’s prefix (first 8 chars), and the scopes — never the full key value.

Common variations

  • Emergency rotation (key is actively compromised). Skip the grace window: create the new key, revoke the old one before updating the integration. Accept the short outage. Investigate the exposure: check the audit log for unexpected actor_type=service_account entries between the suspected leak and the revoke.
  • Scheduled rotation on a compliance calendar. Create the new key, set expires_at on the old key to a date 7 days out. Integrations that switch inside the window work through the cutover; any that miss it fail at expiry and get attention fast.
  • Gateway API keys. Gateway pairing keys (api_key_hash on the gateways table) use a different flow — re-pair the gateway rather than rotating the key via this page. See the installer how-tos.

If this didn’t work

  • Integration returns 401 after you updated the key — the integration cached the old key. Restart it, or force a reload of its secret store.
  • Integration returns 403 on some endpoints after rotation — the new key has a narrower scope than the old one. Create a new key with the correct scope, push it, then revoke the wrong-scope key.
  • “Revoke” is disabled — you are looking at a gateway-owned key. Use the gateway unpair flow instead.
  • Create Key returns 403 — your role is operator. API key issuance is admin/owner-only per D81 and D83.