Rotation

Endpoint reference for rotation policies and schedules. For the guide, see Rotation Policies. For the model, see Rotation.

Base path: /v1/rotation/

GET /v1/rotation/policies#

List rotation policies.

Query: active_only, limit, cursor.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "data": [
    {
      "id": "rot_quarterly",
      "name": "quarterly",
      "interval": "90d",
      "interval_seconds": 7776000,
      "grace_period": "48h",
      "auto_generate": false,
      "is_active": true,
      "secrets_count": 15
    }
  ],
  "cursor": null,
  "has_more": false
}

Scope: admin.

POST /v1/rotation/policies#

Create.

Body:

Scope: admin.

GET /v1/rotation/policies/{id}#

Scope: admin.

PATCH /v1/rotation/policies/{id}#

Partial update.

Scope: admin.

DELETE /v1/rotation/policies/{id}#

Delete. Attached secrets are detached.

Scope: admin.

POST /v1/rotation/policies/{id}/enable#

Enable a paused policy.

Scope: admin.

POST /v1/rotation/policies/{id}/disable#

Pause without detaching secrets.

Scope: admin.

POST /v1/rotation/policies/{id}/secrets#

Assign a secret to the policy.

Body: {"secret_path": "..."}.

Response 201 Created: SecretAssignment object.

Scope: admin.

DELETE /v1/rotation/policies/{id}/secrets/{secret_path}#

Detach a secret (path URL-encoded).

Scope: admin.

POST /v1/rotation/policies/{id}/rotate#

Trigger rotation for the policy.

Body (optional): {"secret_paths": ["..."]} to scope to specific paths.

Response: array of RotationHistoryItem.

Scope: secrets:rotate.

GET /v1/rotation/policies/{id}/history#

List rotation events.

Query: status (success|failed|pending), limit, cursor.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "data": [
    {
      "id": "rh_abc",
      "policy_id": "rot_quarterly",
      "secret_path": "...",
      "status": "success",
      "old_version": 3,
      "new_version": 4,
      "rotated_at": "2026-04-23T00:00:00Z",
      "rotated_by": "system:rotation-scheduler"
    }
  ],
  "has_more": false
}

Scope: audit:read.

GET /v1/rotation/due#

Secrets due for rotation.

Query: within_hours (default 24), include_overdue (default true), policy_id.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "secrets": [
    {
      "path": "...",
      "policy_id": "rot_quarterly",
      "policy_name": "quarterly",
      "next_rotation_at": "2026-04-30T00:00:00Z",
      "is_overdue": false
    }
  ]
}

Scope: secrets:rotate or admin.

GET /v1/rotation/pending#

Deprecated alias for /v1/rotation/due. Same response shape.

Secret policies (value generation)#

GET /v1/secret-policies#

List.

POST /v1/secret-policies#

Create a value-generation policy (length, charset, require classes).

GET /v1/secret-policies/{id}#

PATCH /v1/secret-policies/{id}#

DELETE /v1/secret-policies/{id}#

Attach via secret_policy_id on a rotation policy or on a secret's options.

Related#

• Rotation Policies
• Rotation (Concepts)
• Events and Webhooks