Credential rotation & revocation

Every device credential — an API key, a PSK, or an X.509 client certificate — has a lifecycle. Rotation replaces a credential while the device keeps running; revocation kills a credential the instant you believe it is compromised. The two are deliberately different operations with different guarantees, and choosing the right one matters: rotate when a credential is simply old, revoke when it has leaked.

This page covers the API key and PSK flows. For how credentials are first issued and presented, see Device identity & credentials.

The credential lifecycle

A credential moves through a small set of states. Rotation and revocation are the two transitions you drive as an operator.

stateDiagram-v2
  [*] --> active : issued at provisioning
  active --> overlapping : rotate (new key issued)
  overlapping --> active : overlap window ends\n(old key rejected)
  active --> revoked : revoke (immediate)
  overlapping --> revoked : revoke (immediate)
  revoked --> [*]

• active — the credential authenticates normally. A device has exactly one active credential per type at steady state.
• overlapping — a rotation is in progress. Both the old and the new credential authenticate. This window exists so the device can pick up the new credential on its own schedule without a gap in connectivity.
• revoked — the credential is dead. Every future request using it returns UNAUTHENTICATED, and any live protocol session it authenticated is torn down where the transport supports it.

Note

A credential value is shown exactly once, at the moment it is issued — both at provisioning and on rotation. CORE-M stores only a hash, a prefix, and metadata. If you lose a freshly rotated key before the device picks it up, rotate again rather than trying to recover it.

Rotation with an overlap window

The whole point of rotation is zero downtime. When you rotate, CORE-M:

1. Generates a new credential and returns it once.
2. Keeps the old credential valid for a configured overlap window.
3. Rejects the old credential as soon as the window ends.

During the overlap window both credentials authenticate, so a device can fetch and apply its new credential on its own schedule — on next boot, on a maintenance poll, or pushed via device RPC — without ever presenting an invalid one. Set the window longer than your worst-case device check-in interval.

timeline
  title API key rotation timeline
  Rotate issued : K1 active : K2 issued (returned once)
  Overlap window : K1 valid : K2 valid
  Window ends : K1 rejected : K2 active

Rotate an API key

1. Rotate the credential. As a tenant admin (or a token with the devices:write scope), call the rotate endpoint for the device. Supply the overlap window in seconds.

   curl -X POST https://api.kronoxdata.com/api/v1/devices/dev_8f3a/credentials/rotate \
     -H "Authorization: Bearer <tenant-admin-jwt>" \
     -H "Content-Type: application/json" \
     -d '{
       "credential_type": "api_key",
       "overlap_seconds": 86400
     }'

2. Capture the new key from the response. It is returned once. The old key’s prefix is echoed so you can confirm which credential is being retired.

   {
     "device_id": "dev_8f3a",
     "credential_type": "api_key",
     "new_api_key": "sk_live_9Qk3pR2wXn7vJ4mB...",
     "new_prefix": "sk_live_9Qk3",
     "previous_prefix": "sk_live_2Ab7",
     "overlap_expires_at": "2026-05-30T12:00:00Z"
   }

3. Deliver the new key to the device. Push it however your fleet picks up config — a shared attribute, an RPC, or the device’s own scheduled poll. Until the device switches, it keeps authenticating with the old key.

4. Let the window close. At overlap_expires_at the old key (sk_live_2Ab7…) stops authenticating and returns UNAUTHENTICATED. No further action is needed.

An audit event device.credential.rotated is written for every rotation, recording the actor, the device, and the credential prefixes — never the raw key.

Rotate a PSK

Pre-shared keys (used by CoAP/DTLS and LwM2M devices) rotate the same way. The difference is only in the credential type and what the device must reconfigure on its DTLS stack.

curl -X POST https://api.kronoxdata.com/api/v1/devices/dev_8f3a/credentials/rotate \
  -H "Authorization: Bearer <tenant-admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_type": "psk",
    "overlap_seconds": 172800
  }'

{
  "device_id": "dev_8f3a",
  "credential_type": "psk",
  "psk_identity": "dev_8f3a",
  "new_psk": "3f9c1d7a8b2e4f60a1c5d9e2f7b3a4c6...",
  "overlap_expires_at": "2026-05-31T12:00:00Z"
}

Caution

A DTLS session is established at handshake time. A device that is already connected with the old PSK keeps its session until it next reconnects — the overlap window covers exactly this gap. Make the PSK overlap window comfortably longer than your DTLS session lifetime so a device that reconnects mid-rotation always has a valid key to hand.

Immediate revocation

Revocation is for the bad day: a key checked into a public repo, a stolen device, a contractor who left. There is no overlap window — the credential is rejected at once.

1. Revoke the credential. Identify it by prefix (revocation never needs the raw value).

   curl -X POST https://api.kronoxdata.com/api/v1/devices/dev_8f3a/credentials/revoke \
     -H "Authorization: Bearer <tenant-admin-jwt>" \
     -H "Content-Type: application/json" \
     -d '{
       "credential_type": "api_key",
       "prefix": "sk_live_2Ab7"
     }'

2. Effects are immediate. From this point on:

   • Every request using the revoked credential returns UNAUTHENTICATED.
   • Active protocol sessions authenticated by it are disconnected where the transport supports it (an MQTT client is dropped, a DTLS session is torn down).
   • Event profile.credential.revoked.{tenant}.{device} is published so downstream consumers (alerting, dashboards) react in real time.

3. Re-credential the device. A revoked device cannot send telemetry until it has a fresh credential. Either rotate in a replacement (if one credential of a pair is still good) or re-provision the device to issue a new one.

Danger

Revocation has no grace period by design. If the device is still in the field and you revoke its only credential, it goes dark until you give it a new one. When the device is trusted and you simply want to retire an old key, rotate — don’t revoke.

Rotate vs revoke: which one?

Situation	Use	Why
Credential is old / past your rotation policy age	Rotate	No downtime; device migrates during the overlap window.
Scheduled, routine key hygiene	Rotate	Overlap window absorbs check-in timing.
Key leaked, device stolen, suspected compromise	Revoke	Cuts off the attacker immediately, sessions included.
Decommissioning a device for good	Revoke	No reason to keep any credential valid.

When and why to rotate

• On a schedule. Set a maximum credential age in your device profile’s credentials policy and rotate before it expires. Routine rotation limits the blast radius of a key you don’t yet know has leaked.
• On personnel or infrastructure change. Rotate after anyone with access to provisioning material leaves, or after you migrate the systems that hold keys.
• After a near-miss. A key that might have been exposed but where the device is still trusted: rotate with a short overlap, then confirm the old prefix stops appearing in last_used metadata before considering it clean.

Tip

Scoped API tokens and service accounts (for backend integrations, not devices) rotate with the same overlap-window model. See Security & compliance for token scopes, IP allowlists, and the audit trail.

Where to go next

Related

• Device identity & credentials — how API keys, PSKs, and certs are first issued and presented.
• Security & compliance — token scopes, audit log, and revocation events.
• Device RPC — one way to push a rotated credential to a device on demand.