Skip to main content

API keys and rotation

Every call to the Customer API carries an API key of an API user in the X-API-Key header. The customer creates API users in the customer portal under Integrations > API Users. Each API user has its own permissions, optional IP whitelist and organization scope, and one or more keys.

Keys​

  • Format. nuntiq_ck_, the environment (live, test or dev), an underscore, 8 hex characters, an underscore, 43 base64url characters and a 6-character checksum, for example nuntiq_ck_live_1a2b3c4d_.... Everything up to the second-last underscore (nuntiq_ck_live_1a2b3c4d) is the key prefix. It is not secret: the portal, the emails and the webhook events use it to name a key. The environment tells you at a glance which platform a key belongs to; a key of another environment is refused with 401 and a message that names both environments. The checksum lets secret scanners recognise a real Nuntiq key. Keys created before this format (nk_1a2b3c4d_..., and keys from before 11 October 2026 without a prefix) keep working until they expire or are rotated.
  • Shown once. A key is shown only when it is created or rotated, in the portal dialog or in the answer of the rotate call. Nuntiq stores only a keyed hash and cannot show a key again. Store it in your secret store straight away.
  • Every key expires. A key is valid for at most 365 days, and 365 days is the default.
  • Several keys. An API user can have up to 5 keys that are active or in their grace period, so two systems or two environments can each use their own key.
  • Older keys. Keys created before October 2026 are 64 hex characters without the nk_ start. They keep working until they expire, 12 months after the change. Rotate them to get a key in the new format.

Rotation and the grace period​

Rotating a key creates a new key and keeps the old one working for the API user's grace period, so every system can switch without downtime. The grace period is 24 hours unless the customer set another value on the API user (1 to 168 hours). After it the old key is refused.

While a replaced key is in its grace period, every answer to a call made with it carries the header X-API-Key-Grace-Until with the time it stops working (ISO 8601, UTC). Watch for this header: it means your system still uses a key that was replaced.

A key in its grace period cannot be rotated again. Rotate its replacement instead.

Refusals​

StatuscodeMeaning
401unauthorizedNo key, or a key Nuntiq does not know
403api_key_expiredThe key passed its expiry date
403api_key_revokedThe key was revoked
403api_key_rotatedThe key was replaced and its grace period ended
403forbiddenThe API user is inactive or outside its active dates, or the IP address is not allowed

The message names the key by its prefix and last four characters, never the key itself.

Manage your own keys through the API​

An API user can list, rotate and revoke its own keys with the key it calls with. No permission is needed. A new key (as opposed to a rotation) is created only in the portal.

The examples use the production base URL https://api.apreceiving.com/api.

List your keys​

GET /v1/api-user/keys answers the keys of the calling API user, newest first, without key values. current: true marks the key used for the call. The answer also gives rotation_grace_hours, key_limit and max_lifetime_days.

curl https://api.apreceiving.com/api/v1/api-user/keys \
  -H "X-API-Key: $NUNTIQ_API_KEY"

Each key has id, label, display (for example nuntiq_ck_live_1a2b3c4d...wXyZ), prefix, last_4, status (active, grace, rotated, expired, revoked), created_at, created_via (portal, admin, api, migration), expires_at, last_used_at, grace_until, revoked_at and replaced_by_key_id.

Rotate the key you call with​

POST /v1/api-user/keys/rotate creates a new key and answers it once, with status 201. The body is optional: label (default: the label of the calling key) and expires_in_days (1 to 365, default 365).

curl -X POST https://api.apreceiving.com/api/v1/api-user/keys/rotate \
  -H "X-API-Key: $NUNTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "ERP production", "expires_in_days": 365 }'
{
  "key": "nuntiq_ck_live_5e6f7a8b_...",
  "key_id": "3f2c...",
  "id": "3f2c...",
  "label": "ERP production",
  "display": "nuntiq_ck_live_5e6f7a8b...Q9xA",
  "status": "active",
  "expires_at": "2027-10-11T14:00:00.000Z",
  "replaced_key": {
    "id": "9a1d...",
    "display": "nuntiq_ck_live_1a2b3c4d...wXyZ",
    "works_until": "2026-10-12T14:00:00.000Z"
  },
  "note": "Store this key now; it is not shown again. The replaced key keeps working until works_until."
}

Refusals: 409 key_already_rotated (the calling key is in its grace period), 409 key_not_active, 409 key_limit (5 keys are active or in grace; revoke one first), 400 invalid_label or invalid_expiry, and 429 rotation_rate_limited (more than 10 rotations through the API in an hour for one API user).

Send the rotate call without an Idempotency-Key header. Nuntiq keeps idempotent answers for 24 hours, and this answer holds the new key. The answer of the rotate call is never written to the request log.

Revoke another of your keys​

POST /v1/api-user/keys/{key_id}/revoke revokes one of the API user's other keys at once, for example the replaced key once every system uses the new one. A key cannot revoke itself (409 cannot_revoke_current_key); rotate it, or revoke it with another key or in the portal.

curl -X POST https://api.apreceiving.com/api/v1/api-user/keys/9a1d.../revoke \
  -H "X-API-Key: $NUNTIQ_API_KEY"

Other refusals: 400 invalid_key_id, 404 key_not_found (not a key of this API user, or already revoked).

Notification emails​

The customer gives every API user one or more notification addresses in the portal (Integrations > API Users, tab Notification Emails). Nuntiq emails them when a key is created, rotated or revoked (also when the integration rotated or revoked it through the API), 30, 7 and 1 days before a key expires, and once when a key has expired. Each address has its own switches, and every email links to a page where the recipient changes which emails it gets. The emails never contain a key.

Webhook events​

Two webhook events follow the keys of the tenant's API users:

  • api_key.rotated: a key was created, rotated or revoked (action created, rotated or revoked), in the portal or through the API.
  • api_key.expiring: a key expires in 30, 7 or 1 days (days_left).

When a key has expired there is no webhook event, only the email. Keys in their grace period and revoked keys get no reminders. Payloads: webhooks.

An integration that rotates its own key before it expires:

  1. Subscribe a webhook to api_key.expiring (or check expires_at from GET /v1/api-user/keys once a day).
  2. When the event arrives for the key you use (key_id), call POST /v1/api-user/keys/rotate with that key.
  3. Store the new key in your secret store before anything else.
  4. Switch every system that uses the old key to the new one, before replaced_key.works_until.
  5. Optionally revoke the old key with the new one (POST /v1/api-user/keys/{old key id}/revoke) once every system has switched. Otherwise it stops at the end of the grace period.

Systems that share the API user can subscribe to api_key.rotated to learn that the key changed.

If the answer of the rotate call is lost (a timeout, a crash before the key was stored), the new key cannot be shown again, and the old key, now in its grace period, cannot be rotated a second time. Ask the customer to create a new key in the portal before the grace period ends. Revoke the unused key (the old key's replaced_by_key_id in GET /v1/api-user/keys) with the old key or in the portal.