Skip to main content
The API uses RS256-signed JWT bearer tokens. There is no API-key mode — every authenticated request carries a per-user access token obtained through the auth flow below.

​
Roles

Every account has one or more roles, carried as claims inside the access token: Endpoints under API Reference → Admin, and the write endpoints under Inventory (Admin), require ADMIN or SUPER_ADMIN. Everything else that requires auth accepts any authenticated user unless the endpoint description says otherwise.

​
Retail sign-up

1

Register

POST /v1/auth/register with email, password, first/last name, and phone. The account is created unverified and a 6-digit code is emailed to the address given.
2

Verify email

POST /v1/auth/verify-email with the email and code. The code expires 10 minutes after it’s sent — use POST /v1/auth/verify-email/resend to get a new one. On success, this returns the same token pair as login.
3

Log in

POST /v1/auth/login with email and password returns accessToken, refreshToken, and expiresIn (seconds).

​
Wholesale (trade) sign-up

Trade accounts go through a review step rather than self-serve verification:
  1. POST /v1/wholesale/apply — public, no password collected. Returns a human-readable tracking ID (e.g. CRA-2658190). This creates the account under review; no login is possible yet.
  2. An admin approves or rejects the application (API Reference → Admin → Wholesale Applications).
  3. On approval, a create-password code is emailed. POST /v1/wholesale/create-password with that code activates the account and returns a token pair.

​
Admin login

Back-office staff (ADMIN / SUPER_ADMIN) use the same POST /v1/auth/login endpoint as everyone else — there’s no separate admin login route. Once TOTP is enabled on the account (see Two-factor authentication), login rejects a request with no totpCode (400 TOTP code required for admin accounts); retry the same call with { email, password, totpCode } to complete it. Forgotten passwords go through the standard OTP-based reset flow, also shared with retail/trade accounts:
  1. POST /v1/auth/forgot-password with { email } — emails a 6-digit OTP code if the account exists (the response doesn’t reveal whether it does).
  2. POST /v1/auth/reset-password with { email, code, newPassword } — sets the new password.

​
Using the access token

Send it as a standard bearer token on every authenticated request:
Access tokens are short-lived (15 minutes). When one expires, call POST /v1/auth/refresh with the refresh token (valid 7 days) to get a new pair. POST /v1/auth/logout invalidates the current refresh token.
There’s no token-refresh middleware baked into this API — client applications are expected to catch 401s and call /v1/auth/refresh themselves before retrying.

​
Two-factor authentication (TOTP)

Any authenticated user can turn on TOTP (Google Authenticator-style) 2FA:
  • POST /v1/auth/totp/setup — generates a secret and QR code.
  • POST /v1/auth/totp/verify — confirms the code from the authenticator app and turns 2FA on.
  • POST /v1/auth/totp/disable — turns it back off.

​
Optional auth

A few catalogue endpoints (product detail, “just for you” recommendations) accept a bearer token if present but don’t require one — pass a token to personalize the response, or omit it entirely for anonymous browsing. These are called out individually in the reference.