Overview
Everything in the Authentication section (X-API-Key /
X-Timestamp / X-Signature) is for merchants integrating the payment
API. /v1/users/* is a completely separate identity system: passwordless
login for the end-user app (web/mobile) via email/phone OTP, wallet signature
(SIWE-style), or Google Sign-In. It requires no HMAC headers at all — auth
endpoints are public, and profile endpoints use a JWT bearer token instead.
Every login method resolves to the same kind of user account, protected by
a short-lived JWT access token plus a rotating refresh token. Refresh tokens
are never stored in plaintext on our end, so treat yours with the same care
as a password.
Login methods
| Method | How it works |
|---|---|
| Email OTP | 6-digit code emailed to the user, verified server-side |
| Phone OTP | 6-digit code sent by SMS, verified server-side |
| Wallet | Sign a server-issued nonce with a wallet private key |
| Client-side Google Sign-In, server verifies the ID token |
If a Google account's email is verified and already belongs to an existing user (from a prior email-OTP login), the Google identity is linked to that account instead of creating a duplicate.
Token lifetimes
Access tokens are short-lived (15 minutes) and can't be revoked early once
issued, so treat them as expiring quickly by design. Refresh tokens last 30
days and can be revoked any time via logout or logout-all. Every call to
/refresh rotates the token — the old refresh token is invalidated and a
new pair is issued, so always persist the latest pair and discard the old
one.