curl --request POST \
  --url https://api.arize.com/v2/api-keys/{api_key_id}/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "id": "<string>",
  "name": "<string>",
  "redacted_key": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by_user_id": "<string>",
  "key": "<string>",
  "description": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "last_used_at": "2023-11-07T05:31:56Z"
}

{
  "status": 400,
  "title": "Invalid request parameters",
  "detail": "The 'name' field is required and must be a non-empty string.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}

{
  "status": 401,
  "title": "Authentication required",
  "detail": "You must be authenticated to access this resource.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}

{
  "status": 403,
  "title": "Access forbidden",
  "detail": "You do not have permission to access this resource.",
  "instance": "/resource/12345",
  "type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}

{
  "status": 404,
  "title": "Resource not found",
  "detail": "The requested resource with ID '12345' was not found.",
  "instance": "/resource/12345",
  "type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}

{
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "One or more fields failed validation.",
  "instance": "/resource/12345",
  "type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}

{
  "status": 429,
  "title": "Rate limit exceeded",
  "detail": "You have exceeded the allowed number of requests. Please try again later.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}

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. Requires the developer user permission flag. Returns 403 when this flag is absent.
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.

This endpoint is in beta, read more here.

POST

api-keys

{api_key_id}

refresh

curl --request POST \
  --url https://api.arize.com/v2/api-keys/{api_key_id}/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "id": "<string>",
  "name": "<string>",
  "redacted_key": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by_user_id": "<string>",
  "key": "<string>",
  "description": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "last_used_at": "2023-11-07T05:31:56Z"
}

{
  "status": 400,
  "title": "Invalid request parameters",
  "detail": "The 'name' field is required and must be a non-empty string.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}

{
  "status": 401,
  "title": "Authentication required",
  "detail": "You must be authenticated to access this resource.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}

{
  "status": 403,
  "title": "Access forbidden",
  "detail": "You do not have permission to access this resource.",
  "instance": "/resource/12345",
  "type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}

{
  "status": 404,
  "title": "Resource not found",
  "detail": "The requested resource with ID '12345' was not found.",
  "instance": "/resource/12345",
  "type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}

{
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "One or more fields failed validation.",
  "instance": "/resource/12345",
  "type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}

{
  "status": 429,
  "title": "Rate limit exceeded",
  "detail": "You have exceeded the allowed number of requests. Please try again later.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}

Authorizations

Authorization

string

header

required

Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format

Path Parameters

api_key_id

string

required

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

Example:

"RW50aXR5OjEyMzQ1"

Body

application/json

Optional body for tightening expiry on the new key and/or setting a grace period on the old key. Refresh cannot extend a key's lifetime: with an empty body the refreshed key inherits the old key's expiry, and an explicit expires_at later than the old key's expiry is rejected with 422.

expires_at

string<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.

Example:

"2027-01-01T00:00:00Z"

grace_period_seconds

integer

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).

Required range: 0 <= x <= 86400

Example:

300

Response

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

The refreshed API key credential and its metadata. Refresh replaces the key secret but preserves the key's identity (ID, name, type, bindings). Unlike key creation, refresh does not return bot_user details — refresh never creates a new service account and the existing bot user's bindings are unchanged.

string

required

Unique identifier for the API key.

name

string

required

User-defined name for the API key.

key_type

enum<string>

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.

Available options:

USER,

SERVICE

status

enum<string>

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.

Available options:

ACTIVE,

REVOKED

redacted_key

string

required

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

created_at

string<date-time>

required

Timestamp when the key was created.

created_by_user_id

string

required

ID of the user who created the key.

key

string

required

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

description

string

Optional user-defined description for the API key.

expires_at

string<date-time>

Optional timestamp when the key will expire.

last_used_at

string<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.

Create an API key Revoke an API key

⌘I

API reference

API clients

Refresh an API key

Authorizations

Path Parameters

Body

Response