Quickstart

Before you start

You need an active Vouchify merchant owner account. Token management is deliberately interactive: sign in with email + OTP (or another supported identity flow) to obtain a JWT, then use that JWT to create the server credential.

1. Choose the smallest access set

Every API token needs one or more explicit scopes. Start with the operation your integration must perform—not with the broadest preset.

A scope is an additional permission ceiling. It cannot override an inactive owner, an inactive merchant, changed ownership, a missing merchant permission, or an unsupported route.

2. Create the token with a JWT

The easiest route is the token console: enter the merchant owner's email, verify the six-digit OTP, choose scopes, and copy the one-time plaintext response. You can also call the management API directly.

JWT='interactive-jwt-from-otp-or-oauth'

curl -X POST 'https://api.usevouchify.com/api/v1/api-tokens' \
  -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Production analytics",
    "scopes": ["dashboard:read", "vouchers:read"],
    "expiresAt": "2026-11-09T00:00:00.000Z"
  }'

3. Make the first request

Send the complete token in the bearer header. Do not place it in the query string.

export VOUCHIFY_TOKEN='vou_<43-character-base64url-secret>.v1'

curl 'https://api.usevouchify.com/api/v1/merchant/stats' \
  -H "Authorization: Bearer $VOUCHIFY_TOKEN"

Handle structured failures

const response = await fetch(
  'https://api.usevouchify.com/api/v1/merchant/stats',
  {
    headers: {
      Authorization: `Bearer ${process.env.VOUCHIFY_TOKEN}`
    }
  }
);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const stats = await response.json();

Treat 401 as an authentication or credential-lifecycle issue. Treat 403 as a scope, route policy, merchant status, role, or existing-permission issue.

Production checklist

• Use one token per integration or environment.
• Choose a descriptive, case-insensitively unique name.
• Store the plaintext in a dedicated secret manager.
• Set an explicit expiry and rotation owner.
• Handle immediate invalidation during rotation.
• Stop retry loops on invalid credentials.