Rotate Access Key

POST

http://localhost:8080/apis/auth/v2/access-keys/:jti/rotate

POST

/apis/auth/v2/access-keys/:jti/rotate

curl -X POST http://localhost:8080/apis/auth/v2/access-keys/jti/rotate \
     -H "Authorization: Bearer <accessToken>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "new_key": {
    "jti": "string",
    "principal": "string",
    "status": "ACTIVE",
    "issuer": "string",
    "audiences": [
      "string"
    ],
    "created_at": "2024-01-15T09:30:00Z",
    "token": "string",
    "token_type": "string",
    "name": "string",
    "description": "string",
    "entity_type": "USER",
    "scope": [
      "string"
    ],
    "expires_at": "2024-01-15T09:30:00Z",
    "grace_period_expires_at": "2024-01-15T09:30:00Z",
    "last_used_at": "2024-01-15T09:30:00Z",
    "service_attributes": {}
  },
  "previous_jti": "string",
  "previous_status": "ACTIVE",
  "grace_period_seconds": 1,
  "grace_period_expires_at": "2024-01-15T09:30:00Z"
}

Authentication

AuthorizationBearer

Supply a raw Helix access token. The Authorization header's Bearer prefix is added automatically.

Path parameters

jtistringRequiredformat: "^ak_[0-9a-f]{32}$"

Stable JWT ID of the Scoped Access Key for the lifecycle operation.

Request

This endpoint expects an object.

grace_period_secondsinteger or nullOptional>=1

Grace period in seconds for the rotated-out key. Omit to use auth.access_keys.rotation_grace_period_seconds. Subject to auth.access_keys.max_rotation_grace_period_seconds.

Response

Successful Response

new_keyobject

Newly minted successor Scoped Access Key. Its raw token is returned only once.

previous_jtistring

Stable JWT ID of the Scoped Access Key that was rotated out.

previous_statusenum

Effective status of the rotated-out key immediately after this request. Normally ROTATING, but may already read as REVOKED or EXPIRED if reconciling this request’s outcome was itself delayed past the grace deadline or a concurrent revoke.

Allowed values:

grace_period_secondsinteger

Seconds the rotated-out key remains usable before it is treated as revoked.

grace_period_expires_atdatetime or nullOptional

Timestamp when the rotated-out key’s grace period expires.

Errors

400

Bad Request Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

501

Not Implemented Error