API Keys

Overview

The Confident AI SDK exposes every API Key method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List API Keys

Lists every API key scoped to the project, newest first. Each key's value is masked — the full value is only ever returned once, by the response that issues it. A rotation whose grace period has already run out is completed before the list is read, so a shadowValue here is always still in flight.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.list_api_keys()

For async mode, call a_list_api_keys and await it as shown below:

result = await project.a_list_api_keys(...)

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.listApiKeys();

Returns

This method returns an object of type ApiKeyList.

Create API Key

Mints a new project-scoped API key. The full value is returned exactly once, in this response, and can never be retrieved again — store it securely. This is the key your application uses to send traces and run evaluations against the project.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.create_api_key(name="CI pipeline", expires_in_days=90)

For async mode, call a_create_api_key and await it as shown below:

result = await project.a_create_api_key(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. A label for the key, shown on the Confident AI platform.
`expires_in_days`	`Optional[int]`	How long the key lasts, in days from now — a duration, not a date. Confident AI turns it into the `expiresAt` instant on the key. Omit it for a key that never expires.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.createApiKey(
  "CI pipeline",
  { expiresInDays: 90 },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. A label for the key, shown on the Confident AI platform.
`expiresInDays`	`number`	How long the key lasts, in days from now — a duration, not a date. Confident AI turns it into the `expiresAt` instant on the key. Omit it for a key that never expires.

Returns

This method returns an object of type CreatedApiKey.

Get API Key

Retrieves one project-scoped API key by id, with its value masked. A rotatesAt in the past means the grace period is over and the outgoing value is already rejected on authentication, even though this endpoint still shows it; listing the keys completes the rotation.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.get_api_key(api_key_id=1420)

For async mode, call a_get_api_key and await it as shown below:

result = await project.a_get_api_key(...)

Parameters

Parameter	Type	Description
`api_key_id`	`str`	Required. The id of the API key.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.getApiKey(1420);

Parameters

Parameter	Type	Description
`apiKeyId`	`string`	Required. The id of the API key.

Returns

This method returns an object of type ApiKey.

Update API Key

Activates or deactivates a project-scoped API key. A deactivated key is rejected on authentication from the next request onwards, so anything still sending traces with it starts failing; its value is unchanged and reactivating it brings the same value back. Rotating is the only way to change the value.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.update_api_key(api_key_id=1420, valid=False)

For async mode, call a_update_api_key and await it as shown below:

result = await project.a_update_api_key(...)

Parameters

Parameter	Type	Description
`api_key_id`	`str`	Required. The id of the API key.
`valid`	`bool`	Required. Send false to deactivate the key, true to reactivate it. A deactivated key is rejected on every request, and deactivating one takes effect immediately.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.updateApiKey(1420, false);

Parameters

Parameter	Type	Description
`apiKeyId`	`string`	Required. The id of the API key.
`valid`	`boolean`	Required. Send false to deactivate the key, true to reactivate it. A deactivated key is rejected on every request, and deactivating one takes effect immediately.

Returns

This method returns an object of type ApiKey.

Delete API Key

Permanently revokes a project-scoped API key. Both its current value and any replacement value in flight stop authenticating at once, so anything still sending traces with it starts failing. This cannot be undone — a new key has to be created in its place.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.delete_api_key(api_key_id=1420)

For async mode, call a_delete_api_key and await it as shown below:

result = await project.a_delete_api_key(...)

Parameters

Parameter	Type	Description
`api_key_id`	`str`	Required. The id of the API key.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.deleteApiKey(1420);

Parameters

Parameter	Type	Description
`apiKeyId`	`string`	Required. The id of the API key.

Returns

This method returns an object of type ApiKeyRef.

Rotate API Key

Rotates a project-scoped API key in place — same id, name and history, and no second key is created. The new value is returned exactly once, in this response. Requests made with the outgoing value during a grace period carry Sunset and X-Api-Key-Warning headers, which is the window to redeploy. Reviving an expired key cannot take a grace period.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.rotate_api_key(
    api_key_id=1420,
    grace_period_in_hours=24,
    expires_in_days=90,
)

For async mode, call a_rotate_api_key and await it as shown below:

result = await project.a_rotate_api_key(...)

Parameters

Parameter	Type	Description
`api_key_id`	`str`	Required. The id of the API key.
`grace_period_in_hours`	`Optional[int]`	How long the current value keeps authenticating alongside the new one, in hours from now — a duration, not a date, stored on the key as `rotatesAt` and never set past `expiresAt`. Defaults to 0, which replaces the value immediately and stops the old one at once.
`expires_in_days`	`Optional[int]`	A new lifetime for the key, in days from now — a duration, not a date, stored on the key as `expiresAt`. Omit it to keep the current expiry, or send null to remove the expiry altogether. Required when rotating a key that has already expired.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.rotateApiKey(
  1420,
  { gracePeriodInHours: 24, expiresInDays: 90 },
);

Parameters

Parameter	Type	Description
`apiKeyId`	`string`	Required. The id of the API key.
`gracePeriodInHours`	`number`	How long the current value keeps authenticating alongside the new one, in hours from now — a duration, not a date, stored on the key as `rotatesAt` and never set past `expiresAt`. Defaults to 0, which replaces the value immediately and stops the old one at once.
`expiresInDays`	`number \| null`	A new lifetime for the key, in days from now — a duration, not a date, stored on the key as `expiresAt`. Omit it to keep the current expiry, or send null to remove the expiry altogether. Required when rotating a key that has already expired.

Returns

This method returns an object of type RotatedApiKey.

Methods (Stateless)

These methods take every argument themselves, so a caller reaches them through client.projects without opening a Project first.

List API Keys

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.list_api_keys(project_id="<PROJECT-ID>")

For async mode, call a_list_api_keys and await it as shown below:

result = await client.projects.a_list_api_keys(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the key belongs to.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.listApiKeys("<PROJECT-ID>");

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the key belongs to.

Returns

This method returns an object of type ApiKeyList.

Create API Key

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.create_api_key(
    project_id="<PROJECT-ID>",
    name="CI pipeline",
    expires_in_days=90,
)

For async mode, call a_create_api_key and await it as shown below:

result = await client.projects.a_create_api_key(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the key belongs to.
`name`	`str`	Required. A label for the key, shown on the Confident AI platform.
`expires_in_days`	`Optional[int]`	How long the key lasts, in days from now — a duration, not a date. Confident AI turns it into the `expiresAt` instant on the key. Omit it for a key that never expires.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.createApiKey(
  "<PROJECT-ID>",
  "CI pipeline",
  { expiresInDays: 90 },
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the key belongs to.
`name`	`string`	Required. A label for the key, shown on the Confident AI platform.
`expiresInDays`	`number`	How long the key lasts, in days from now — a duration, not a date. Confident AI turns it into the `expiresAt` instant on the key. Omit it for a key that never expires.

Returns

This method returns an object of type CreatedApiKey.

Get API Key

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.get_api_key(
    project_id="<PROJECT-ID>",
    api_key_id=1420,
)

For async mode, call a_get_api_key and await it as shown below:

result = await client.projects.a_get_api_key(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the key belongs to.
`api_key_id`	`str`	Required. The id of the API key.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.getApiKey("<PROJECT-ID>", 1420);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the key belongs to.
`apiKeyId`	`string`	Required. The id of the API key.

Returns

This method returns an object of type ApiKey.

Update API Key

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.update_api_key(
    project_id="<PROJECT-ID>",
    api_key_id=1420,
    valid=False,
)

For async mode, call a_update_api_key and await it as shown below:

result = await client.projects.a_update_api_key(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the key belongs to.
`api_key_id`	`str`	Required. The id of the API key.
`valid`	`bool`	Required. Send false to deactivate the key, true to reactivate it. A deactivated key is rejected on every request, and deactivating one takes effect immediately.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.updateApiKey(
  "<PROJECT-ID>",
  1420,
  false,
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the key belongs to.
`apiKeyId`	`string`	Required. The id of the API key.
`valid`	`boolean`	Required. Send false to deactivate the key, true to reactivate it. A deactivated key is rejected on every request, and deactivating one takes effect immediately.

Returns

This method returns an object of type ApiKey.

Delete API Key

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.delete_api_key(
    project_id="<PROJECT-ID>",
    api_key_id=1420,
)

For async mode, call a_delete_api_key and await it as shown below:

result = await client.projects.a_delete_api_key(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the key belongs to.
`api_key_id`	`str`	Required. The id of the API key.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.deleteApiKey("<PROJECT-ID>", 1420);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the key belongs to.
`apiKeyId`	`string`	Required. The id of the API key.

Returns

This method returns an object of type ApiKeyRef.

Rotate API Key

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.rotate_api_key(
    project_id="<PROJECT-ID>",
    api_key_id=1420,
    grace_period_in_hours=24,
    expires_in_days=90,
)

For async mode, call a_rotate_api_key and await it as shown below:

result = await client.projects.a_rotate_api_key(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the key belongs to.
`api_key_id`	`str`	Required. The id of the API key.
`grace_period_in_hours`	`Optional[int]`	How long the current value keeps authenticating alongside the new one, in hours from now — a duration, not a date, stored on the key as `rotatesAt` and never set past `expiresAt`. Defaults to 0, which replaces the value immediately and stops the old one at once.
`expires_in_days`	`Optional[int]`	A new lifetime for the key, in days from now — a duration, not a date, stored on the key as `expiresAt`. Omit it to keep the current expiry, or send null to remove the expiry altogether. Required when rotating a key that has already expired.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.rotateApiKey(
  "<PROJECT-ID>",
  1420,
  { gracePeriodInHours: 24, expiresInDays: 90 },
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the key belongs to.
`apiKeyId`	`string`	Required. The id of the API key.
`gracePeriodInHours`	`number`	How long the current value keeps authenticating alongside the new one, in hours from now — a duration, not a date, stored on the key as `rotatesAt` and never set past `expiresAt`. Defaults to 0, which replaces the value immediately and stops the old one at once.
`expiresInDays`	`number \| null`	A new lifetime for the key, in days from now — a duration, not a date, stored on the key as `expiresAt`. Omit it to keep the current expiry, or send null to remove the expiry altogether. Required when rotating a key that has already expired.

Returns

This method returns an object of type RotatedApiKey.

Types

ApiKey

An API key as it reads after it has been issued, with both secrets masked. Organization-scoped and project-scoped keys have the same shape; a key's scope is fixed when it is created and shows in the prefix of its value (confident_<region>_org_ or confident_<region>_proj_).

class ApiKey:
    id: int
    name: Optional[str]
    valid: bool
    created_at: str
    expires_at: Optional[str] = Field(alias="expiresAt")
    value: str
    shadow_value: Optional[str] = Field(alias="shadowValue")
    rotates_at: Optional[str] = Field(alias="rotatesAt")
    last_used: Optional[str] = Field(alias="lastUsed")

idintRequired

The id of the API key, generated by Confident AI.

Example: 1420

nameOptional[str]Required

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validboolRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstrRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expires_atOptional[str]Required

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestrRequired

The key, masked: fifteen asterisks followed by its last six characters. The full value is returned only by the response that issues it — creating a key, or rotating one — and never again.

Example: "***************LmNoPq"

shadow_valueOptional[str]Required

The masked replacement value while a rotation's grace period is running, or null when no rotation is pending.

Example: "***************Tu6vWx"

rotates_atOptional[str]Required

When a pending rotation completes — shadowValue becomes value and the old value stops authenticating — or null when no rotation is pending.

Example: "2025-03-01T12:00:00+00:00"

last_usedOptional[str]Required

When the key last authenticated a request, or null when it never has.

Example: "2025-02-28T18:45:12+00:00"

interface ApiKey {
  id: number;
  name: string | null;
  valid: boolean;
  created_at: string;
  expiresAt: string | null;
  value: string;
  shadowValue: string | null;
  rotatesAt: string | null;
  lastUsed: string | null;
}

idnumberRequired

The id of the API key, generated by Confident AI.

Example: 1420

namestring | nullRequired

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validbooleanRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstringRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expiresAtstring | nullRequired

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestringRequired

The key, masked: fifteen asterisks followed by its last six characters. The full value is returned only by the response that issues it — creating a key, or rotating one — and never again.

Example: "***************LmNoPq"

shadowValuestring | nullRequired

The masked replacement value while a rotation's grace period is running, or null when no rotation is pending.

Example: "***************Tu6vWx"

rotatesAtstring | nullRequired

When a pending rotation completes — shadowValue becomes value and the old value stops authenticating — or null when no rotation is pending.

Example: "2025-03-01T12:00:00+00:00"

lastUsedstring | nullRequired

When the key last authenticated a request, or null when it never has.

Example: "2025-02-28T18:45:12+00:00"

ApiKeyList

The API keys of one organization or one project. There is no pagination: the whole set is returned.

class ApiKeyList:
    api_keys: List[ApiKey] = Field(alias="apiKeys")

api_keysList[ApiKey]Required

Every API key in the requested scope, newest first. Each key's secrets are masked.

See ApiKey.

interface ApiKeyList {
  apiKeys: ApiKey[];
}

apiKeysApiKey[]Required

Every API key in the requested scope, newest first. Each key's secrets are masked.

See ApiKey.

ApiKeyRef

Confirmation that an API key was revoked. The key's row is deleted and both of its values stop authenticating at once.

class ApiKeyRef:
    id: int

idintRequired

The id of the API key that was revoked.

Example: 1420

interface ApiKeyRef {
  id: number;
}

idnumberRequired

The id of the API key that was revoked.

Example: 1420

CreatedApiKey

A newly minted API key, carrying the only copy of its full value.

class CreatedApiKey:
    id: int
    name: Optional[str]
    valid: bool
    created_at: str
    expires_at: Optional[str] = Field(alias="expiresAt")
    value: str
    shadow_value: Optional[Any] = Field(alias="shadowValue")
    rotates_at: Optional[Any] = Field(alias="rotatesAt")
    last_used: Optional[Any] = Field(alias="lastUsed")

idintRequired

The id of the API key, generated by Confident AI.

Example: 1420

nameOptional[str]Required

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validboolRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstrRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expires_atOptional[str]Required

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestrRequired

The full API key. This response is the only place it is ever returned, so store it now — every later response masks it, and a lost value can only be replaced by rotating the key.

Example: "confident_us_org_9mJq2sVb1hXk4pR7tYw0aZc3eF6gH8iJ0kLmNoPq"

shadow_valueOptional[Any]Required

Always null on a key that has just been created; only a rotation with a grace period puts a second value in flight.

rotates_atOptional[Any]Required

Always null on a key that has just been created.

last_usedOptional[Any]Required

Always null on a key that has just been created; it is set the first time the key authenticates a request.

interface CreatedApiKey {
  id: number;
  name: string | null;
  valid: boolean;
  created_at: string;
  expiresAt: string | null;
  value: string;
  shadowValue: null | null;
  rotatesAt: null | null;
  lastUsed: null | null;
}

idnumberRequired

The id of the API key, generated by Confident AI.

Example: 1420

namestring | nullRequired

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validbooleanRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstringRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expiresAtstring | nullRequired

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestringRequired

The full API key. This response is the only place it is ever returned, so store it now — every later response masks it, and a lost value can only be replaced by rotating the key.

Example: "confident_us_org_9mJq2sVb1hXk4pR7tYw0aZc3eF6gH8iJ0kLmNoPq"

shadowValuenull | nullRequired

Always null on a key that has just been created; only a rotation with a grace period puts a second value in flight.

rotatesAtnull | nullRequired

Always null on a key that has just been created.

lastUsednull | nullRequired

Always null on a key that has just been created; it is set the first time the key authenticates a request.

RotatedApiKey

A just-rotated API key. Which variant you get follows gracePeriodInHours: without one the new secret is value and shadowValue is null, with one the new secret is shadowValue and value is the masked outgoing key.

RotatedApiKey = Union[
    ImmediatelyRotatedApiKey,
    PendingRotationApiKey,
]

type RotatedApiKey =
  | ImmediatelyRotatedApiKey
  | PendingRotationApiKey;

A RotatedApiKey is one of the shapes below. Send the fields of one of them, never a mix of both.

The result of rotating without a grace period: value has already been replaced and the previous value stopped authenticating the moment this response was produced.

class ImmediatelyRotatedApiKey:
    id: int
    name: Optional[str]
    valid: bool
    created_at: str
    expires_at: Optional[str] = Field(alias="expiresAt")
    value: str
    shadow_value: Optional[Any] = Field(alias="shadowValue")
    rotates_at: Optional[Any] = Field(alias="rotatesAt")
    last_used: Optional[str] = Field(alias="lastUsed")

idintRequired

The id of the API key, generated by Confident AI.

Example: 1420

nameOptional[str]Required

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validboolRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstrRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expires_atOptional[str]Required

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestrRequired

The new full API key. This response is the only place it is ever returned, so store it now — every later response masks it.

Example: "confident_us_org_5tRw8xYz2aBc4dEf6gHi8jKl0mNo2pQr4sTu6vWx"

shadow_valueOptional[Any]Required

Always null: the rotation completed as this request was served, so no second value is in flight.

rotates_atOptional[Any]Required

Always null: no rotation is pending.

last_usedOptional[str]Required

When the key last authenticated a request, or null when it never has.

Example: "2025-02-28T18:45:12+00:00"

interface ImmediatelyRotatedApiKey {
  id: number;
  name: string | null;
  valid: boolean;
  created_at: string;
  expiresAt: string | null;
  value: string;
  shadowValue: null | null;
  rotatesAt: null | null;
  lastUsed: string | null;
}

idnumberRequired

The id of the API key, generated by Confident AI.

Example: 1420

namestring | nullRequired

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validbooleanRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstringRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expiresAtstring | nullRequired

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestringRequired

The new full API key. This response is the only place it is ever returned, so store it now — every later response masks it.

Example: "confident_us_org_5tRw8xYz2aBc4dEf6gHi8jKl0mNo2pQr4sTu6vWx"

shadowValuenull | nullRequired

Always null: the rotation completed as this request was served, so no second value is in flight.

rotatesAtnull | nullRequired

Always null: no rotation is pending.

lastUsedstring | nullRequired

When the key last authenticated a request, or null when it never has.

Example: "2025-02-28T18:45:12+00:00"

The result of rotating with a grace period: two values authenticate at once, the outgoing one until rotatesAt and the new one from now on.

class PendingRotationApiKey:
    id: int
    name: Optional[str]
    valid: bool
    created_at: str
    expires_at: Optional[str] = Field(alias="expiresAt")
    value: str
    shadow_value: str = Field(alias="shadowValue")
    rotates_at: str = Field(alias="rotatesAt")
    last_used: Optional[str] = Field(alias="lastUsed")

idintRequired

The id of the API key, generated by Confident AI.

Example: 1420

nameOptional[str]Required

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validboolRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstrRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expires_atOptional[str]Required

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestrRequired

The outgoing key, masked. It keeps authenticating alongside shadowValue until rotatesAt, then stops.

Example: "***************LmNoPq"

shadow_valuestrRequired

The new full API key, issued by this rotation. This response is the only place it is ever returned, so store it now — every later response masks it. It authenticates immediately and becomes value once rotatesAt passes.

Example: "confident_us_org_5tRw8xYz2aBc4dEf6gHi8jKl0mNo2pQr4sTu6vWx"

rotates_atstrRequired

When the grace period ends: shadowValue becomes value and the outgoing value is rejected. Confident AI computes it from the gracePeriodInHours duration and never sets it past expiresAt.

Example: "2025-03-01T12:00:00+00:00"

last_usedOptional[str]Required

When the key last authenticated a request, or null when it never has.

Example: "2025-02-28T18:45:12+00:00"

interface PendingRotationApiKey {
  id: number;
  name: string | null;
  valid: boolean;
  created_at: string;
  expiresAt: string | null;
  value: string;
  shadowValue: string;
  rotatesAt: string;
  lastUsed: string | null;
}

idnumberRequired

The id of the API key, generated by Confident AI.

Example: 1420

namestring | nullRequired

The label for the key, shown on the Confident AI platform.

Example: "CI pipeline"

validbooleanRequired

Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.

Example: true

created_atstringRequired

When the key was created.

Example: "2025-01-15T09:30:00+00:00"

expiresAtstring | nullRequired

The instant the key stops authenticating, or null when it never expires. Confident AI computes it from the expiresInDays duration sent when the key was created or last rotated.

Example: "2025-04-15T09:30:00+00:00"

valuestringRequired

The outgoing key, masked. It keeps authenticating alongside shadowValue until rotatesAt, then stops.

Example: "***************LmNoPq"

shadowValuestringRequired

Example: "confident_us_org_5tRw8xYz2aBc4dEf6gHi8jKl0mNo2pQr4sTu6vWx"

rotatesAtstringRequired

When the grace period ends: shadowValue becomes value and the outgoing value is rejected. Confident AI computes it from the gracePeriodInHours duration and never sets it past expiresAt.

Example: "2025-03-01T12:00:00+00:00"

lastUsedstring | nullRequired

When the key last authenticated a request, or null when it never has.

Example: "2025-02-28T18:45:12+00:00"

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI