Rotate Project API Key

(v2)

POST

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.

POST/v2/projects/{projectId}/api-keys/{apiKeyId}/rotate

curl -X POST "https://api.confident-ai.com/v2/projects/{projectId}/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

projectIdstringRequired
The id of the project the key belongs to.
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 Project API 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