Authentication

Vantemo uses API keys for programmatic access. Keys follow the Stripe/Shopify convention and are designed for both server-side and client-side use cases.

API Key Format

All keys follow the pattern: vt_{type}_{environment}_{random}

vt_sk_live_a1b2c3d4e5f6g7h8i9j0
│  │  │    └─ 20+ character random string
│  │  └────── environment: live or test
│  └───────── type: pk (publishable), sk (secret), rk (restricted)
└──────────── prefix: always "vt"

Key Types

Publishable Keys (vt_pk_)

Read-only access to storefront data. Safe to expose in browser JavaScript.

Scopes: storefront:read

// OK to embed in client-side code
const products = await fetch('/v1/storefront/products', {
  headers: { Authorization: 'Bearer vt_pk_live_...' },
});

Secret Keys (vt_sk_)

Full access to both storefront and admin APIs. Never expose in client-side code.

Scopes: storefront:read, storefront:write, admin:read, admin:write

// NEVER expose in browser code
const orders = await fetch('/v1/admin/orders', {
  headers: { Authorization: 'Bearer vt_sk_live_...' },
});

Restricted Keys (vt_rk_)

Custom scope selection for third-party integrations. Created with only the permissions the integration needs.

Scopes: Any combination of available scopes

Available Scopes

Security

Hash-Only Storage

API keys are stored as SHA-256 hashes. The full key is returned once on creation and can never be retrieved again. If you lose a key, revoke it and create a new one.

Rate Limiting

Each API key has a configurable rate limit (default: 60 requests per minute). Rate limiting uses a Redis sliding window algorithm for accurate enforcement.

Every response includes rate limit headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1709164800

When the limit is exceeded, the API returns 429 Too Many Requests.

Key Expiration

Keys can be created with an optional expiration date. Expired keys are automatically rejected. We recommend setting expiration dates for keys shared with third parties.

Key Revocation

Revoked keys are immediately rejected. Revocation is permanent — there's no way to un-revoke a key. Navigate to Settings → API Keys in the admin dashboard to revoke a key.

Authentication Flow

Client Request
  │
  ├─ Has "Authorization: Bearer vt_..." header?
  │   ├─ Yes → Hash the key → Look up by hash
  │   │   ├─ Found + valid → Set tenant context → Continue
  │   │   ├─ Found + expired/revoked → 401 Unauthorized
  │   │   └─ Not found → 401 Unauthorized
  │   │
  │   └─ Check rate limit → 429 if exceeded
  │
  └─ No Bearer token → Fall through to session auth (admin dashboard)

Best Practices

1. Use the least-privileged key type. Publishable keys for client-side, restricted keys for integrations, secret keys only for your own servers.
2. Set expiration dates for keys shared with third parties.
3. Rotate keys periodically — revoke old keys and create new ones.
4. Never commit keys to version control. Use environment variables.
5. Monitor key usage — the admin dashboard shows last-used timestamps for each key.

Next Steps

• Quickstart — Make your first API call
• API Reference — Browse all endpoints
• Webhooks — Subscribe to platform events