Sign in

v2

latestOpenAPI 3.0.3Apache-2.02026-08-07119359591.9 KB
API Keys

Refresh an API key

Atomically revoke an existing API key and issue a replacement with the same metadata (name, description, and key type).

The old key is invalidated and the new key is activated in a single transaction — there is no window where neither key is valid. The full new key value (key) is only returned once in the response. Store it securely.

Authorization:

  • User keys: The creator or an account admin may refresh the key.
  • Service keys: space admins (and higher) may refresh any service key in their space. Non-admins require the SERVICE_KEY_CREATE permission and must be the creator of the key.

Expiry behaviour: expires_at is required when the existing key has an expiry — omitting it would extend the key's lifetime to unbounded and is rejected with 422. For unbounded existing keys, expires_at may be omitted (the replacement is also unbounded) or supplied to add a specific expiry. The value must not be later than the existing key's expiry; to issue a key with a longer lifetime, use POST /v2/api-keys.

Grace period: Supply grace_period_seconds in the request body to keep the old key valid for that many seconds after the refresh. If not supplied, the old key is revoked immediately.

<Note>This endpoint is in beta, read more here.</Note>

post/v2/api-keys/{api_key_id}/refresh

Path parameters

api_key_idstring required

A universally unique identifier (base64-encoded opaque string).

Example:RW50aXR5OjEyMzQ1

The unique API key identifier (base64)

Request body

expires_atstring date-time

Expiration timestamp for the refreshed key. Required when the existing key has an expiry — omitting it would extend the key's lifetime to unbounded, which is rejected with 422. For an unbounded existing key, expires_at may be omitted (the refreshed key is also unbounded) or provided to add a specific expiry. The value must be no later than the old key's expiry — a request that would extend the key's lifetime is rejected with 422. To create a key with a longer lifetime, use POST /v2/api-keys to issue a new key rather than refreshing.

grace_period_secondsinteger

Grace period in seconds during which the old key remains valid after the refresh. When set, the old key's expiration is updated to now + grace_period_seconds instead of being immediately revoked — it expires naturally at the end of the window. If the old key already has an expires_at that is sooner than the grace window end, the shorter value is used (the grace period cannot extend a key's original lifetime). Defaults to 0 (immediate revocation). Maximum is 86400 (24 hours).

Example request

{
  "expires_at": "2027-01-01T00:00:00Z",
  "grace_period_seconds": 300
}

Response

Refreshed API key. The raw replacement key is only returned once.

idstring required

Unique identifier for the API key.

namestring required

User-defined name for the API key.

descriptionstring

Optional user-defined description for the API key.

key_type'USER' | 'SERVICE' required

Type of the API key.

  • USER - Personal key that authenticates as the creating user.
  • SERVICE - Key that authenticates as a service account with explicitly granted access.
status'ACTIVE' | 'REVOKED' required

Current status of the API key.

  • ACTIVE - The key is valid for use.
  • REVOKED - The key has been revoked and is no longer valid.
redacted_keystring required

Redacted version of the key suitable for display (e.g., "ak-abc...xyz").

created_atstring date-time required

Timestamp when the key was created.

expires_atstring date-time

Optional timestamp when the key will expire.

created_by_user_idstring required

ID of the user who created the key.

last_used_atstring date-time

Approximate timestamp when the key was last used for authentication. This value is periodically updated and may not reflect the most recent usage.

keystring required

The full replacement API key value. Only returned once during refresh. Store it securely — it cannot be retrieved again.