Skip to main content
Python

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your workspace API key. See Find your API key for more information.

Path Parameters

​
workspaceId
string<uuid>
required

The workspace id.

​
apiKeyId
string<uuid>
required

The API key id.

Body

application/json
​
gracePeriodHours
integer
default:0

Hours the previous secret keeps authenticating. The default of 0 retires it immediately. It never outlives expiresAt. Only one previous secret is kept, so rotating again during a grace period retires the older one immediately.

Required range: 0 <= x <= 168
Example:

24

​
expiresAt
any

Response

200 - application/json

The rotated key. It keeps its id and name, and the new secret is in secret.

​
id
string<uuid>
required
read-only

The API key id.

​
dateCreated
string<date-time>
required
read-only

The API key creation date.

​
dateUpdated
string<date-time>
required
read-only

The API key last update date.

​
dateLastUsed
string<date-time> | null
required
read-only

The API key last use date.

​
secureKey
string
required
read-only

An obfuscated hint of the API key value. When a key is created or rotated this also holds the full secret, for backward compatibility; prefer secret.

Maximum string length: 120
Example:

"sk-o...5PW0"

​
status
enum<string>
required
read-only

The key's lifecycle state. active: the current secret authenticates. rotating: the key was rotated and the previous secret still authenticates until previousKeyExpiresAt. expired: expiresAt has passed, no secret authenticates, and the key can't be rotated.

Available options:
active,
rotating,
expired
Example:

"active"

​
name
string | null

The API key name.

Maximum string length: 120
Example:

"Secret Key"

​
secret
string
read-only

The full API key. Only present in the response that creates or rotates the key, and never shown again.

Example:

"sk-ol-Xq3v9Rk2mPz8TnW4yL7bC1dF5hJ6"

​
expiresAt
string<date-time> | null

When the key stops authenticating. null means the key never expires. Set when the key is created or rotated, and must be in the future. When the request is authenticated with an API key that expires, the result can't be later than that key's expiry. On create, omit it to inherit that expiry. On rotate, omit it to keep the current one. It can't be changed with an update; rotate the key instead.

Example:

"2027-01-01T00:00:00Z"

​
lastRotatedAt
string<date-time> | null
read-only

When the key was last rotated.

​
previousKeyExpiresAt
string<date-time> | null
read-only

While status is rotating, when the previous secret stops authenticating.