Credentials

Update a service credential

Rename a credential, retarget its agent identity, change its expiry, or change its grant. At least one field must be present.

A new scopes array replaces the grant outright; it is not merged. It is bounded by what the caller holds, exactly as it is on creation, so a credential editing itself can only ever narrow. An attempt to widen answers 403 scope_escalation and names the refused scopes.

Setting expiresAt to null removes the expiry; setting it to a timestamp in the past is refused. Omitting it leaves the expiry alone.

Supplying an explicit grant also clears isLegacy: once an operator has said what a grandfathered credential should hold, it is no longer grandfathered.

A revoked credential cannot be updated and answers 409 credential_state. Accepts an Idempotency-Key; a retry with the same key replays the original response instead of re-applying the update.

patch/credentials/{credentialId}

Request

  • Base URL: https://inkseal.net/api/v1
  • URL: https://inkseal.net/api/v1/credentials/{credentialId}
  • 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.

Request body

namestring
agentIdentitystring
scopesCredentialScope[]

Replaces the grant outright; not merged. Bounded by what the caller holds, so a credential editing itself can only narrow. Supplying this also clears isLegacy.

expiresAtstring date-time nullable

A future timestamp to set an expiry, or null to remove one. A past timestamp is refused.

pausedboolean

True pauses this credential, false lifts the pause. A paused credential authenticates nothing and answers 401 unauthorized, like a revoked one, but its keys survive so lifting the pause needs no rotation.

Example request

{
  "name": "Contract intake agent (EU)",
  "agentIdentity": "intake-bot-eu@ops.example.com",
  "scopes": [
    "documents:write",
    "envelopes:write"
  ],
  "expiresAt": "2027-06-30T23:59:59.000Z",
  "limits": {
    "maxCreditsPerDay": 25,
    "maxSendsPerHour": 5
  },
  "paused": true
}

Response

The credential as it now stands.

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
    }
  }
}

Changes

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