API Keys

Refresh an API key

Changed on

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.

When developer access is disabled for an account, refreshing a user key or service key returns 403.

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.

Account key lifetime limit: If your account limits the maximum API key lifetime, an expires_at beyond that maximum is rejected with 422. When the existing key has no expiry and expires_at is omitted, the refreshed key expires at the maximum lifetime from now. To bring a key that exceeds the limit into compliance, supply a compliant expires_at.

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

Request

  • Base URL
    https://api.arize.com
  • URL
    https://api.arize.com/v2/api-keys/{api_key_id}/refresh
  • Auth
    HTTP bearer

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. If your account limits the maximum API key lifetime, a value beyond that maximum is rejected with 422. Providing a compliant value lets you bring a key that exceeds the limit into policy. When the existing key has no expiry and expires_at is omitted, the refreshed key expires at the maximum lifetime from now.

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.

Changes

  • 02f159248661Revision changes
    • breaking

      the response's body type changed from no type to object for status

    • info

      removed subschema #2 from the response body allOf list for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • 4f94eb2fd1abRevision changes
    • warning

      added the new ACTIVE enum value to the //// response property for the response status

    • warning

      added the new REVOKED enum value to the //// response property for the response status

    • warning

      added the new SERVICE enum value to the //// response property for the response status

    • warning

      added the new USER enum value to the //// response property for the response status

    • info

      api operation id api_keys_refresh removed and replaced with refresh_api_key

    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the optional property //// to the response with the status

    • info

      removed the active enum value from the //// response property for the response status

    • info

      removed the deleted enum value from the //// response property for the response status

    • info

      removed the service enum value from the //// response property for the response status

    • info

      removed the user enum value from the //// response property for the response status