> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://arize.com/docs/ax/rest-reference#api-version-stages).
## OpenAPI
````yaml https://api.arize.com/v2/spec.yaml post /v2/api-keys/{api_key_id}/refresh
openapi: 3.0.3
info:
title: Arize REST API
version: 2.0.0
description: |
API specification for the backend data server. The API is hosted globally
at https://api.arize.com/v2 or in your own environment.
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- description: Global
url: https://api.arize.com
- description: Regional
url: https://api.{region}.arize.com
variables:
region:
default: eu-west-1a
enum:
- eu-west-1a
- ca-central-1a
- description: Custom Host
url: https://{host}
variables:
host:
default: api.arize.com
security:
- bearerAuth: []
tags:
- name: AI Integrations
description: |
AI integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
entire account, a specific organization, or a specific space.
- name: Annotation Configs
description: >
Annotation configs allow you to define consistent annotation schemas that
can be reused across your workspace, ensuring evaluations are structured
and
comparable over time.
- name: Annotation Queues
description: >
Annotation queues help you organize and manage human evaluation workflows.
Use queues to assign spans or examples to annotators for review and
labeling.
- name: API Keys
description: >
API keys are used to authenticate requests to the Arize API. List your
keys
to view metadata; the raw secret is never returned after creation.
- name: Audit Logs
description: >
Audit logs record authenticated user actions within an account, providing
a
chronological trail for security and compliance review. Access requires
account admin privileges and audit logging to be enabled.
- name: Datasets
description: |
Datasets are structured, version-controlled example collections you use to
run, evaluate, and track LLM experiments.
- name: Evaluators
description: >
Evaluators are reusable evaluation configurations used to assess the
quality
of LLM outputs. They can be template-based (using LLM judges) or
code-based.
- name: Experiments
description: >
Experiments let you systematically test prompt/model changes using
datasets,
tasks, and evaluators.
- name: Integrations
description: >
Integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
PagerDuty, Slack), and
your own agents. Integrations can be scoped to the entire account, a
specific
organization, or a specific space.
- name: Monitors
description: >
Monitors continuously track a metric over your model or LLM application
data
and alert you when it crosses a threshold. Each monitor watches a single
metric - data quality, model performance, drift, a custom metric, or a
tracing metric - and moves between statuses as the metric passes in and
out of its
healthy range.
- name: Organizations
description: >
Organizations are top-level containers within an Arize AX account for
grouping spaces.
- name: Projects
description: |
Projects represent LLM applications being monitored in Arize where you can
observe traces and spans.
- name: Prompts
description: >
Prompts are reusable, versioned templates for LLM interactions. Use
prompts
to standardize and manage how you interact with LLMs across your
application.
- name: Resource Restrictions
description: |
Endpoints for restricting and unrestricting resources (projects, models).
- name: Role Bindings
description: |
Role bindings assign a role to a user on a resource. REST currently
supports space- and project-scoped bindings.
- name: Roles
description: >
Roles define sets of permissions that can be assigned to users within an
account. Create custom roles to tailor access control to your team's
needs.
- name: Spaces
description: >
Spaces are containers within an organization for grouping related
projects,
datasets, and experiments, enabling collaboration or isolated
experimentation
with role-based access control.
- name: Spans
description: |
Spans represent individual operations within a trace. A span captures the
timing, status, and attributes of a single operation in your application.
- name: Tasks
description: |
Tasks are configurable units of work that tie one or more evaluators to a
data source (project or dataset). Use tasks to automate evaluation of LLM
outputs, with support for continuous evaluation and backfill runs.
- name: Traces
description: |
A trace is the collection of spans sharing a trace ID, representing a
single end-to-end request through an LLM application. Use the Traces
endpoint to retrieve traces with all of their spans in one call.
- name: Users
description: >
Users represent members of an account. The Users endpoints allow creating,
listing, updating (display name), and removing users from the account
programmatically.
paths:
/v2/api-keys/{api_key_id}/refresh:
post:
tags:
- API Keys
summary: Refresh an API key
description: >
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](https://arize.com/docs/ax/rest-reference#api-version-stages).
operationId: refresh_api_key
parameters:
- $ref: '#/components/parameters/ApiKeyIdPathParam'
requestBody:
$ref: '#/components/requestBodies/RefreshApiKeyRequestBody'
responses:
'200':
$ref: '#/components/responses/RefreshApiKeyResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
parameters:
ApiKeyIdPathParam:
name: api_key_id
in: path
description: The unique API key identifier (base64)
required: true
schema:
$ref: '#/components/schemas/Id'
example: QXBpS2V5OjEyMzQ1
requestBodies:
RefreshApiKeyRequestBody:
description: >
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.
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshApiKeyRequest'
examples:
inherit_expiry:
summary: Inherit the old key's expiry (empty body)
value: {}
shorten_expiry:
summary: >-
Shorten expiry for the refreshed key (must be ≤ the old key's
expiry; a later value is rejected with 422)
value:
expires_at: '2027-01-01T00:00:00Z'
with_grace_period:
summary: Keep old key valid for 5 minutes after refresh
value:
grace_period_seconds: 300
responses:
RefreshApiKeyResponse:
description: Refreshed API key. The raw replacement key is only returned once.
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshApiKeyResponse'
BadRequest:
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
Unauthorized:
description: Authentication is required
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
Forbidden:
description: Insufficient permissions to access this resource
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
NotFound:
description: Not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
UnprocessableEntity:
description: Unprocessable entity
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
RateLimitExceeded:
description: Rate limit exceeded
headers:
Retry-After:
description: |
When throttled (429), how long to wait before retrying. Value is
either a delta-seconds integer.
schema:
type: integer
minimum: 0
example: 42
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
schemas:
Id:
type: string
description: A universally unique identifier (base64-encoded opaque string).
example: RW50aXR5OjEyMzQ1
RefreshApiKeyRequest:
type: object
properties:
expires_at:
type: string
format: date-time
description: >
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:
type: integer
minimum: 0
maximum: 86400
description: >
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: 300
additionalProperties: false
RefreshApiKeyResponse:
description: >
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.
allOf:
- $ref: '#/components/schemas/ApiKey'
- type: object
required:
- key
properties:
key:
type: string
description: >
The full replacement API key value. **Only returned once**
during
refresh. Store it securely — it cannot be retrieved again.
Problem:
type: object
description: RFC 9457 Problem Details
properties:
title:
type: string
description: A short, human-readable summary of the problem type
status:
type: integer
description: >-
The HTTP status code generated by the origin server for this
occurrence of the problem
type:
type: string
format: uri-reference
description: A URI reference that identifies the problem type
detail:
type: string
description: >-
A human-readable explanation specific to this occurrence of the
problem
instance:
type: string
format: uri-reference
description: >-
A URI reference that identifies the specific occurrence of the
problem
required:
- title
- status
additionalProperties: false
ApiKey:
type: object
required:
- id
- name
- key_type
- status
- redacted_key
- created_at
- created_by_user_id
properties:
id:
type: string
description: Unique identifier for the API key.
name:
type: string
description: User-defined name for the API key.
description:
type: string
description: Optional user-defined description for the API key.
key_type:
$ref: '#/components/schemas/ApiKeyType'
status:
$ref: '#/components/schemas/ApiKeyStatus'
redacted_key:
type: string
description: >-
Redacted version of the key suitable for display (e.g.,
"ak-abc...xyz").
created_at:
type: string
format: date-time
description: Timestamp when the key was created.
expires_at:
type: string
format: date-time
description: Optional timestamp when the key will expire.
created_by_user_id:
type: string
description: ID of the user who created the key.
last_used_at:
type: string
format: date-time
description: >-
Approximate timestamp when the key was last used for authentication.
This value is periodically updated and may not reflect the most
recent usage.
additionalProperties: false
ApiKeyType:
type: string
enum:
- USER
- SERVICE
description: >
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.
ApiKeyStatus:
type: string
enum:
- ACTIVE
- REVOKED
description: |
Current status of the API key.
- ACTIVE - The key is valid for use.
- REVOKED - The key has been revoked and is no longer valid.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat:
description: >
Most Arize AI endpoints require authentication. For those endpoints that
require authentication, include your API key in the request header using
the format
``` Authorization: Bearer
```
````