OZozav
API Keys

Rotate an API key with an overlap window

Mints a successor key with identical scopes. The previous secret remains valid for the overlap window (default 24 hours, maximum 7 days), then is revoked automatically. Live.

post/api-keys/{api_key_id}/rotate

Request

  • Base URL
    https://developers.ozav.io/v2
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Path parameters

api_key_idstring required

The opaque API-key id (ozav_key_...).

Request body

overlap_hoursinteger

How long the previous secret stays valid after rotation, in hours (0-168; default 24). It is revoked automatically when the window elapses.

Response

Successor key; secret returned once.

idstring required

Opaque API-key identifier, prefixed ozav_key_.

object'api_key' required

Resource type discriminator; always the literal api_key.

namestring

Human-readable label you gave the key.

key_prefixstring required

Non-secret display prefix of the key (e.g. ozav_sk_live_a1b2) - enough to identify it without revealing the secret.

environment'test' | 'live' required

Which environment the key operates against:

  • test - the sandbox; moves no real money.
  • live - production; can move real money.
scopesstring[] required

The scopes granted to this key (intersected with the organization's entitlements at request time).

role'admin' | 'operator' | 'viewer'

The role this key was minted with, when it was minted with one. It is a label and a mint-time template - not part of the permission decision, which stays entitlements ∩ scopes. A rotated key keeps it.

Absent on a key whose scopes were listed one by one, which is every key created before roles existed. The field is omitted rather than sent as null, because null here would read as "this key has no powers" instead of "this key was not minted from a template".

last_used_atstring date-time

When the key was last used to authenticate a request (RFC 3339 / ISO 8601, UTC).

expires_atstring date-time

When the key expires, if it has an expiry (e.g. an old secret's cutover time after a rotation).

created_atstring date-time

When the key was created (RFC 3339 / ISO 8601, UTC).

secretstring

The full secret key; returned only on creation and rotation.

Changes

No recorded changes to this operation across all 1 revision of this API.