Skip to content

API Reference / API keys

Rotate an API key's secret

Gives an existing API key a new secret while keeping its id, name and policies. The current secret keeps working for the chosen grace period (none, one hour or 24 hours) so consumers can switch over, then stops. Rotating again during a grace period ends the earlier secret at once. The new secret is returned only once. A recent two-factor re-verification is required, and the key's owner is emailed.

POST/accounts.v1.Accounts/RotateAPIKey

Request body

application/jsonRequired

Request to give an API key in the caller's workspace a new secret, keeping its id, name and policies. Requires a two-factor step-up in the last 5 minutes, and a non-administrator can rotate only their own keys.

apiKeyId?string

Opaque 16-byte identifier of the API key to rotate, base64-encoded in JSON.

Format"byte" base64

gracestring

How long the current secret keeps working after the rotation: none, one hour or 24 hours. Required.

Value in"API_KEY_ROTATION_GRACE_NONE""API_KEY_ROTATION_GRACE_ONE_HOUR""API_KEY_ROTATION_GRACE_TWENTY_FOUR_HOURS"

Response body

application/json

Success

apiKey?APIKey

The key after rotation, with its new key prefix and, during a grace period, when the previous secret stops working.

Show attributes
createdAt?string

When the key was created.

Format"date-time"

createdBy?string

Opaque 16-byte identifier of the user who created the key and owns it, base64-encoded in JSON.

Format"byte" base64

expiresAt?string

When the key stops authenticating. Requests at or after this time are rejected as unauthenticated. Absent when the key never expires.

Format"date-time"

id?string

Opaque 16-byte identifier of the API key, assigned on creation. Base64-encoded in JSON.

Format"byte" base64

keyPrefix?string

The first 8 characters of the secret, kept so a key can be recognised in lists. Cannot authenticate on its own.

lastUsedAt?string

When the key last authenticated a request. Absent when the key has never been used.

Format"date-time"

name?string

Label chosen when the key was created, 1 to 256 characters, to tell keys apart.

policies?array<string>

Names of the policies granted to the key, at least one, such as "trading" or "steam". ListPolicies lists the valid names and the permissions each grants.

previousKeyExpiresAt?string

When the secret this key had before its last rotation stops authenticating. A time in the past means it has stopped. Absent when the key was never rotated with a grace period, or was last rotated with none.

Format"date-time"

revealable?boolean

Whether RevealAPIKey can return this key's secret. False for a key created before secrets were stored. Rotate it to make it revealable.

workspaceId?string

Opaque 16-byte identifier of the workspace the key is confined to, base64-encoded in JSON.

Format"byte" base64

rawKey?string

The key's new secret, sent as a Bearer token in the Authorization header. Store it securely. RevealAPIKey can return it again after a two-factor step-up.

curl -X POST "https://api.goldmine.to/accounts.v1.Accounts/RotateAPIKey" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyId": "CgsMDQ4PEBESExQVFhcYGQ==",
    "grace": "API_KEY_ROTATION_GRACE_ONE_HOUR"
  }'
{
  "apiKey": {
    "id": "CgsMDQ4PEBESExQVFhcYGQ==",
    "name": "CI deploy key",
    "keyPrefix": "9c41d07e",
    "workspaceId": "AAECAwQFBgcICQoLDA0ODw==",
    "createdAt": "2026-06-29T12:00:00Z",
    "policies": [
      "trading"
    ],
    "previousKeyExpiresAt": "2026-11-08T13:00:00Z"
  },
  "rawKey": "9c41d07e5b2a8f3d6e1c0b9a8f7e6d5c4b3a2918f7e6d5c4b3a29180f7e6d5c4"
}