Vouchify
Token console

Quick links

Quickstart GuideAPI reference 66 endpointsAuthentication GuideScopes & presets 32 scopesToken lifecycle GuideErrors ReferenceToken console Tool
↑↓ Navigate↵ OpenEsc Close
Documentation menu
QuickstartAuthenticationScopes & presetsToken lifecycleErrorsSecurityJWT & other authAPI referenceToken console

Authentication boundaries

JWT & other auth routes

Understand what merchant API tokens deliberately cannot do, when an interactive JWT is required, and where Vouchify uses entirely separate credentials.

Interactive JWTPerson present
API tokenIntegration present
Other keyDedicated contract

JWT and API token are not interchangeable

PropertyInteractive JWTMerchant API token
RepresentsA signed-in user sessionA merchant-owned integration
Created throughOTP or OAuth authenticationJWT-only management API
Best forSensitive user-driven operationsScoped server-to-server business operations
Scope metadataBypasses API-token scope checksMust satisfy explicit route policy
Shared enforcementLive role, merchant, ownership, status, and existing permission checks still apply.
Token management Allowed for active merchant ownerRejected
JWT access is broader, not unguarded.Bypassing API-token scope metadata does not bypass the normal authentication, role, tenant, or permission system.

Token management begins with email + OTP

API.md classifies OTP and token management as JWT-only but does not publish OTP paths or schemas. The token console uses this verified account-authentication contract:

Send OTP
POST /auth/otp/send
Content-Type: application/json

{
  "email": "dev.user@vouchify.local",
  "name": "Dev User",
  "requestFrom": "user-app"
}
Verify OTP
POST /auth/otp/verify
Content-Type: application/json

{
  "email": "dev.user@vouchify.local",
  "code": "123456"
}

The verification response returns interactive access and refresh tokens. This docs console keeps the access token in memory only and does not persist the refresh token.

GET/api-tokensList active, revoked, and logically expired token records.
GET/api-tokens/scopesRead the complete server-defined scope catalog and explicit preset expansions.
POST/api-tokensCreate a merchant-owned API token in the first available slot.
PATCH/api-tokens/:idUpdate an active token's name, explicit scopes, or expiration policy.
POST/api-tokens/:id/rotateAtomically replace the secret while preserving token policy and slot.
POST/api-tokens/:id/revokeIrreversibly and idempotently revoke a token, with an optional bounded reason.
DELETE/api-tokens/:idPermanently delete an inactive record and free its slot.

JWT-only route categories

These are intentionally excluded from merchant API tokens because they change identity, ownership, money movement, sensitive verification state, or the integration credentials themselves.

01Authentication and account security
JWT only

Interactive identity and credential administration do not accept merchant API tokens.

  • OTP send, merchant signup OTP, and OTP verification
  • Google and Apple OAuth flows
  • Refresh token
  • Logout and logout-all
  • Account profile and security operations
  • API-token management routes
02Financial and payment operations
JWT only

API-token wallet support is read-only, and voucher decryption is deliberately excluded.

  • Billing subscription changes, invoice payments, payment verification, and cancellation
  • Wallet withdrawals, deposits, transfers, and payment requests
  • User voucher purchase, activation, extension, top-up, cashout, sharing payments, and card or mobile-money flows
  • User membership purchase, renewal, sharing payments, and payment completion
  • Voucher decryption
03Team and ownership operations
JWT only

Ownership, invitation, and privileged team mutations require interactive JWT authentication.

  • Team invitations
  • Team role changes
  • Team member removal
  • Invite acceptance
  • Merchant ownership claims and ownership-code verification
  • Merchant-group creation, requests, settings mutations, and group membership mutations
  • Admin and delegator-only routes
04KYB and identity operations
JWT only

Merchant API tokens expose only the two documented KYB read routes.

  • KYB field changes
  • KYB document upload and submission
  • Identity-document uploads
  • KYB completion and document proxy operations
05Widget key management
JWT only

JWT owner routes derive the merchant from CurrentUser and reject arbitrary body merchantId selection.

  • Widget-key creation
  • Widget-key detail
  • Widget-key deletion

Separate authentication contracts

Widget API

Widget routes use x-public-key with WidgetApiKeyGuard, not merchant bearer tokens.

  • Widget checkout
  • Widget reads

Callbacks and verification links

Callbacks retain callback authentication and verification links retain dedicated link credentials.

  • pawaPay callbacks
  • Apple Wallet callbacks
  • Withdrawal verification links
Never substitute credentials.A merchant bearer token cannot stand in for x-public-key, callback authentication, or a dedicated verification-link credential.