ReferenceAPI

Rotate the key

Rotate a private-key principal's key, issuing the next one and revoking the current one in the same step.

POST https://api.nevia.cloud/v1/workspaces/{ws}/access/{principal}/keys
curl -X POST "https://api.nevia.cloud/v1/workspaces/01d4cnjjq40hnnh0nwmkg35nv2h/access/01d4cnjmn4fbb1r5btxb5mypv62/keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 8f1c2a7e-3b4d-4c5e-9f0a-1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in": 604800
  }'
{
  "key": {
    "id": "01d4cnjq8r0tvwxyb3c4d5f6g7h",
    "principal": "01d4cnjmn4fbb1r5btxb5mypv62",
    "byok": true,
    "created_by": "01d4cnjmn4fbb1r5btxb5mypv62",
    "expires_at": "2026-09-10T12:34:56Z",
    "last_used_at": "2026-09-10T12:34:56Z",
    "created_at": "2026-09-10T12:34:56Z",
    "revoked_at": "2026-09-10T12:34:56Z"
  },
  "replaced": {
    "id": "01d4cnjq8r0tvwxyb3c4d5f6g7h",
    "principal": "01d4cnjmn4fbb1r5btxb5mypv62",
    "byok": true,
    "created_by": "01d4cnjmn4fbb1r5btxb5mypv62",
    "expires_at": "2026-09-10T12:34:56Z",
    "last_used_at": "2026-09-10T12:34:56Z",
    "created_at": "2026-09-10T12:34:56Z",
    "revoked_at": "2026-09-10T12:34:56Z"
  },
  "key_file": {
    "principal": "01d4cnjmn4fbb1r5btxb5mypv62",
    "subject": "393890846249869905",
    "key_id": "393890846384085404",
    "audience": "https://auth.example.com",
    "token_url": "https://api.example.com/v1/auth/token",
    "private_key": "string"
  },
  "operations": [
    "01d4cnjm89yk0r3xtv80dy0x7by"
  ]
}

Authorization

bearerAuth
Authorization Bearer <token>

Send the token in the Authorization: Bearer <token> header. See Authenticate.

In: header

Path Parameters

ws* string

Workspace id: 27 lowercase letters and digits.

Match ^[A-Za-z0-9_-]{1,64}$
principal* string

Principal id: 27 lowercase letters and digits.

Match ^[A-Za-z0-9_-]{1,64}$

Header Parameters

Idempotency-Key* string

Retry key. A retry with the same key and body replays the first response

Length 1 <= length <= 255

Request Body

application/json

Options for the next key

Behavior

  • Exactly one key is live at every instant.
  • Access tokens from the replaced key, including any minted during the rotation, are refused on their next request.
  • The key file is returned once.
  • An idempotent replay answers key_file: null.

Response

application/json

The new key, the key it replaced, and the key file.