Rotate Organization API Key

POSThttps://api.confident-ai.com/v1/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 immediately and the old value stops authenticating. With a grace period, the new value is issued as shadowValue and both values authenticate until rotatesAt, after which the new value becomes value and the old value is rejected. While the old value is used during a grace period, responses carry Sunset and X-Api-Key-Warning headers announcing when it stops working.

The key's expiration is unchanged unless expiresInDays is provided. Rotating an expired key revives it: expiresInDays is then required (pass null for no expiration) and a grace period is not allowed.

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

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

200

{
  "success": true,
  "data": {
    "apiKey": {
      "id": 12,
      "name": "CI/CD key",
      "valid": true,
      "value": "***************a1b2c3",
      "shadowValue": "confident_org_f7e6d5c4b3a2918js86d93a4b5c6d7e8",
      "rotatesAt": "2024-12-05T23:00:00.000Z",
      "expiresAt": null,
      "created_at": "2024-12-04T23:00:00.000Z",
      "lastUsed": "2024-12-05T10:15:00.000Z"
    }
  }
}

Headers

CONFIDENT_API_KEYstringRequired
The organization API key for your Confident AI organization.

Path parameters

apiKeyIdintegerRequired
The unique identifier of the API key.

Request body

gracePeriodInHoursinteger
How long (in hours) the current value keeps authenticating alongside the new one. 0 replaces the value immediately. The grace period never extends past the key's expiration.
expiresInDaysinteger
Sets a new expiration for the key, counted from now. Omit to keep the current expiration, or pass null to remove it. Required when rotating an expired key.

Response

successboolean
Indicates if the request was successful
dataobject
Show 1 propertyHide 1 property
- apiKeyobject
  Show 9 propertiesHide 9 properties
  - idinteger
    Unique identifier for the API key
  - namestring
    Human-readable label for the API key
  - validboolean
    Whether the key is active. A deactivated key is rejected on authentication.
  - valuestring
    The API key value. This is redacted (only the last 6 characters are shown, prefixed with asterisks) on every response except the create response — and the rotate response when rotating without a grace period — where the full value is returned exactly once.
  - shadowValuestring
    The replacement value while a rotation's grace period is running, or null when no rotation is pending. Redacted on every response except the rotate response that issued it, where the full value is returned exactly once.
  - rotatesAtstring
    ISO 8601 timestamp of when a pending rotation completes and shadowValue replaces value, or null when no rotation is pending
  - expiresAtstring
    ISO 8601 timestamp of when the key expires, or null if it never expires
  - created_atstring
    ISO 8601 timestamp of when the key was created
  - lastUsedstring
    ISO 8601 timestamp of when the key was last used to authenticate, or null if never used

Built byConfident AI