Rotate Key

POSThttps://api.confident-ai.com/v2/organization/api-keys/{apiKeyId}/rotate

Rotates an organization-scoped API key in place — the key keeps its id, name and history, and no second key is created. The new value is returned exactly once, in this response, and can never be retrieved again — store it securely.

With gracePeriodInHours: 0 (the default) the key's value is replaced as this request is served and the outgoing value stops authenticating at once. With a grace period, the new value comes back as shadowValue and both values authenticate until rotatesAt, after which the new value becomes value and the outgoing one is rejected; requests made with the outgoing value in the meantime carry Sunset and X-Api-Key-Warning headers announcing when it stops working.

The key's expiry is left alone unless expiresInDays is sent. Rotating an expired key revives it: expiresInDays is then required (send null for no expiry) and a grace period is not allowed. A rotation whose grace period has already run out is completed before this one starts.

POST/v2/organization/api-keys/{apiKeyId}/rotate

curl -X POST "https://api.confident-ai.com/v2/organization/api-keys/{apiKeyId}/rotate" \
  -H "CONFIDENT_API_KEY: <ORGANIZATION-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "gracePeriodInHours": 24,
  "expiresInDays": 90
}'

200

{
  "success": true,
  "data": {
    "id": 1420,
    "name": "CI pipeline",
    "valid": true,
    "created_at": "2025-01-15T09:30:00.000Z",
    "expiresAt": "2025-04-15T09:30:00.000Z",
    "value": "confident_us_org_5tRw8xYz2aBc4dEf6gHi8jKl0mNo2pQr4sTu6vWx",
    "shadowValue": null,
    "rotatesAt": null,
    "lastUsed": "2025-02-28T18:45:12.000Z"
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The organization API key for your Confident AI organization.

Path parameters

apiKeyIdintegerRequired
The id of the API key.

Request body

gracePeriodInHoursinteger
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.
expiresInDaysinteger | 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.

Response

Rotate Key succeeded.

successboolean
Indicates if the request was successful.
dataobject | object
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.
Show 2 variantsHide 2 variants
- Immediately Rotated API Keyobject
  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.
  Show 9 propertiesHide 9 properties
  - idinteger
    The id of the API key, generated by Confident AI.
  - namestring | null
    The label for the key, shown on the Confident AI platform.
  - validboolean
    Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.
  - created_atstring
    When the key was created.
  - expiresAtstring | null
    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.
  - valuestring
    The new full API key. This response is the only place it is ever returned, so store it now — every later response masks it.
  - shadowValuenull
    Always null: the rotation completed as this request was served, so no second value is in flight.
  - rotatesAtnull
    Always null: no rotation is pending.
  - lastUsedstring | null
    When the key last authenticated a request, or null when it never has.
- OR
- API Key With Rotation Pendingobject
  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.
  Show 9 propertiesHide 9 properties
  - idinteger
    The id of the API key, generated by Confident AI.
  - namestring | null
    The label for the key, shown on the Confident AI platform.
  - validboolean
    Whether the key authenticates. A deactivated key is rejected on every request until it is reactivated.
  - created_atstring
    When the key was created.
  - expiresAtstring | null
    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.
  - valuestring
    The outgoing key, masked. It keeps authenticating alongside shadowValue until rotatesAt, then stops.
  - shadowValuestring
    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.
  - rotatesAtstring
    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.
  - lastUsedstring | null
    When the key last authenticated a request, or null when it never has.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI