Credentials

Rotate a credential's key

Issue a second secret for an existing credential, without downtime.

The credential's identity does not move: same id, same scopes, same audit history, same agentIdentity. Only the key material changes, so nothing downstream sees a new principal.

The new raw key is returned exactly once, here. As with creation, only its hash is stored and there is no way to read it back. The format is unchanged: isk_ plus 40 base62 characters.

Grace window. The outgoing secret keeps authenticating for 24 hours from the moment of rotation, and previousSecretExpiresAt is the exact deadline, read back from storage rather than recomputed, so it is the timestamp to schedule against. Deploy the new key inside that window. After the deadline the old key is dead.

Rotating again inside the window kills the secret that was already on its way out, so a credential never has more than the current secret and one predecessor alive at a time. Rotating twice in quick succession therefore cuts the first window short.

Rotation refuses a credential that has been revoked or has already expired, with 409 credential_state. Revocation, unlike rotation, has no grace period at all.

Accepts an Idempotency-Key; a retry with the same key replays the original response, including the one-time key, instead of burning a second rotation.

post/credentials/{credentialId}/rotate

Request

  • Base URL: https://inkseal.net/api/v1
  • URL: https://inkseal.net/api/v1/credentials/{credentialId}/rotate
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Makes this mutation retry-safe. 1 to 255 printable ASCII characters (0x20 to 0x7e), trimmed before use. The key is scoped to the workspace and the credential that sent it. Reusing it with a different method, path, or payload answers 422 idempotency_key_reuse. A completed attempt replays its stored status and body with an Idempotent-Replay: true response header; 5xx, 429, and non-JSON answers leave the key retryable. A concurrent request holding the 90 second lease answers 409 idempotency_in_progress. Records are retained 24 hours.

Response

The credential, the only copy of its new raw key, and when the outgoing key stops working.

Example response

{
  "data": {
    "id": "V1StGXR8_Z5jdHi6B-myT",
    "name": "Contract intake agent",
    "agentIdentity": "intake-bot@ops.example.com",
    "scopes": [
      "documents:write",
      "envelopes:write",
      "envelopes:send"
    ],
    "isActive": true,
    "createdAt": "2026-08-01T11:02:44.000Z",
    "lastUsedAt": "2026-08-21T07:41:12.338Z",
    "secrets": [
      {
        "prefix": "isk_REDA",
        "lastFour": "CTED",
        "createdAt": "2026-08-01T11:02:44.000Z",
        "lastUsedAt": "2026-08-21T07:41:12.338Z"
      }
    ],
    "limits": {
      "maxCreditsPerDay": 25,
      "maxSendsPerHour": 5
    },
    "key": "isk_REDACTEDREDACTEDREDACTEDREDACTEDREDACTED",
    "previousSecretExpiresAt": "2026-08-22T07:41:12.338Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.