Rotate Organization API Key

(v1)

POST

Rotates an organization-scoped API key in place — it keeps its id, name, and history — and returns the new value exactly once in this response, so store it securely. With the default gracePeriodInHours: 0 the old value stops authenticating immediately; with a grace period the new value is issued as shadowValue and both authenticate until rotatesAt (responses using the old value carry Sunset and X-Api-Key-Warning headers). Expiration is unchanged unless expiresInDays is provided; rotating an expired key revives it, which requires expiresInDays and disallows a grace period.

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