Auth
Choosing a credential
API key vs. OAuth — which one fits your integration.
The public-API-accessible routes (see API Reference) accept either credential, interchangeably, on the same endpoint. Send exactly one:
X-Api-Key: vuz_...header, orAuthorization: Bearer vuz_at_...header
Sending both on the same request is rejected with 400 ambiguous_credentials — pick one.
Comparison
| API key | OAuth 2.0 | |
|---|---|---|
| Best for | Scripts, backend jobs, quick integrations you control yourself | Store plugins (WooCommerce, etc.) a merchant installs and authorizes themselves |
| Who creates it | You, from your own dashboard (Settings → Integrations → API Keys) | The merchant, via an authorize/consent screen — you never see their raw secret |
| Credential shape | Single long-lived secret (vuz_...), you rotate it yourself | Short-lived access token (vuz_at_..., 1 hour) + refresh token, auto-rotated |
| Setup complexity | Low — one API call or a dashboard click | Higher — you register as an OAuth client and implement Authorization Code + PKCE |
| Revocation | You revoke your own key any time | The merchant can revoke access from their VUZ dashboard at any time — your integration must handle a sudden 401 token_revoked |
| Scopes | Set per key at creation | Granted by the merchant on the consent screen |
| Rate limits | Per-key (rateLimitPerMinute/rateLimitPerHour, configurable) | App-tier defaults (120/min, 10,000/hour) |
The rule of thumb
- Building a tool for your own single VUZ business? Use an API key. It's the fastest path — no OAuth flow to implement.
- Building something a third party (a merchant, a customer) installs and connects themselves to their own VUZ business? Use OAuth — never ask a merchant to generate and hand you their API key.
Both paths land in the exact same place: a PublicApiContext bound to one business, with
a set of granted scopes, enforced by the same scope model on every request.