Credential operations

Token lifecycle

Create, observe, edit, rotate, revoke, and clean up merchant credentials without losing sight of one-time secret delivery or slot behavior.

Create

Active

Revoked

Deleted

States and transitions

Stored status is either ACTIVE or REVOKED. List responses derive EXPIRED when an active record's expiration is in the past.

ACTIVE

Usable while the owner, merchant, permissions, scopes, and expiration remain valid.

EXPIRED

Logically inactive, visible in the list, occupies its slot, and may be deleted.

REVOKED

Explicitly and irreversibly inactive, still occupies its slot, and may be deleted.

Slots persist until deletion.A maximum of five stored records exists per merchant. Revoked and expired records do not free capacity automatically.

JWT-only management API

Every operation in this table requires a valid interactive JWT from an active merchant owner. Merchant API tokens are rejected.

GET/api-tokens

List active, revoked, and logically expired token records.

GET/api-tokens/scopes

Read the complete server-defined scope catalog and explicit preset expansions.

POST/api-tokens

Create a merchant-owned API token in the first available slot.

PATCH/api-tokens/:id

Update an active token's name, explicit scopes, or expiration policy.

POST/api-tokens/:id/rotate

Atomically replace the secret while preserving token policy and slot.

POST/api-tokens/:id/revoke

Irreversibly and idempotently revoke a token, with an optional bounded reason.

DELETE/api-tokens/:id

Permanently delete an inactive record and free its slot.

Create: plaintext appears once

Field	Required	Rules
`name`	Yes	Trimmed 1–64 characters; case-insensitively unique per merchant.
`scopes`	Yes	At least one unique supported explicit scope.
`expiresAt`	No	Omitted = 90 days; ISO timestamp ≥24h away; `null` = never expires.

Request body

{
  "name": "Production integration",
  "scopes": ["vouchers:read", "vouchers:redeem"],
  "expiresAt": "2026-11-09T00:00:00.000Z"
}

201 response · abbreviated

{
  "id": "66f000000000000000000001",
  "name": "Production integration",
  "tokenHint": "vou_A1b2C3d4…xYz9.v1",
  "scopes": ["vouchers:read", "vouchers:redeem"],
  "status": "ACTIVE",
  "generation": 1,
  "expiresAt": "2026-11-09T00:00:00.000Z",
  "token": "vou_<one-time-secret>.v1"
}

Copy now, then close.

The token property is never returned by list or detail metadata. Vouchify cannot recover it later.

Edit policy or rotate the secret

Edit policy

Change name, scopes, or expiry. The plaintext secret does not change and clients keep working, subject to the new policy.

Active and unexpired only
Changes apply immediately
At least one field should be sent

Rotate secret

Atomically replace the hash, increment generation, set rotatedAt, and return one new plaintext.

Policy and slot preserved
Old secret invalid immediately
No overlap window

Plan for immediate cutover.Rotation invalidates the old credential before you can deploy the new one. Design a controlled maintenance or secret-distribution sequence.

Revoke, then delete

RevokeIrreversible · idempotent

Delete recordPermanent · frees slot

Revocation accepts an optional reason of at most 256 characters. Repeating the request preserves the original revocation metadata. Deletion returns 204 No Content and is permitted only for revoked or expired records.

What the list can reveal

Token metadata supports operational visibility without retaining the secret or per-request history.

tokenHintscopesstatusexpiresAtgenerationlastUsedAtlastUsedIplastUsedUserAgentrotatedAtrevokedAtrevokedReasoncreatedAtupdatedAt

Usage metadata is updated atomically at most once every five minutes per token. There is no API-token audit-event collection and no request history.