---
title: "Refresh an API key"
method: POST
path: "/v2/api-keys/{api_key_id}/refresh"
tags: ["API Keys"]
---

# Refresh an API key

`POST /v2/api-keys/{api_key_id}/refresh`

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](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Path parameters

- `api_key_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Request body

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

## Response `200`

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

- RefreshApiKeyResponse — 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.
  - `id` string, required — Unique identifier for the API key.
  - `name` string, required — User-defined name for the API key.
  - `description` string — 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_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.
  - `expires_at` string, date-time — Optional timestamp when the key will expire.
  - `created_by_user_id` string, required — ID of the user who created the key.
  - `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.
  - `key` string, required — The full replacement API key value. **Only returned once** during refresh. Store it securely — it cannot be retrieved again.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)