Skip to main content
POST
Rotate an API key

Authorizations

x-api-key
string
header
required

Headers

x-idempotency-key
string<uuid>
required

Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH requests.

A key is scoped to your client, the HTTP method and the path, and is remembered for 24 hours after a successful (below 400) response. Repeating the same request (same JSON body, whatever the key order or whitespace) with the same key within that window returns the original response with X-Idempotent-Replayed: true instead of executing the request again. Using the same key on the same endpoint with a different body returns 422 with problem type idempotency-key-reused; the request is not executed. Error responses (4xx and 5xx) are not remembered, so a request refused for a fixable reason can be corrected and retried under the same key. Request bodies that are not JSON (for example file uploads) are not compared.

Path Parameters

api_key_id
string
required

Unique identifier of the API key to rotate KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

Body

application/json
grace_period_seconds
integer
default:3600

How long the old key keeps working after the rotation, in seconds. Default 3600 (one hour), at most 86400 (one day). 0 stops the old key at once.

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

3600

Response

API key rotated. The response is the new key.

id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

key
string
required

The API key value, shown only once. A key starts with dk_live_ in production and dk_test_ in the sandbox; keys made before these prefixes have none and keep working.

Example:

"dk_live_4KLkSmzQbL6Xs8xnUjssdGHX7PfhHpAb"

name
string
required

A label that says what the key is for. No two live keys of a client share a name.

Required string length: 1 - 128
Example:

"prod-payouts"

scope
enum<string>

What the key can do. The scopes nest: read_only is inside operate, and operate is inside full_access.

  • full_access: everything that an admin of the client can do. A key created without a scope gets it.
  • operate: moves money and runs daily operations, but cannot add recipients or destinations, delete anything, or manage users, keys, signers, policies, mandates or webhooks. Wallet transactions and scheduled payments can still pay an address that is not a saved destination. A wallet transaction needs signatures from the signers of the wallet, and the policies of the wallet apply to it. A scheduled payment goes out only when a mandate of the client covers it.
  • read_only: reads only.

A key does not take the role of the person who created it.

Available options:
full_access,
operate,
read_only
Example:

"read_only"

allowed_cidrs
string[]

The networks the key may be used from. Absent when the key has no IP restriction.

Example:
expires_at
string<date-time>

When the key stops working. Absent when the key never expires.

Example:

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

rotated_from_api_key_id
string

The key this key replaced, when a rotation made it. Absent otherwise.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"