Customer auth

Base path: /v1/auth on the Public API.

Shoppers authenticate with phone OTP. The server issues a customer JWT (typ: "customer").

• Persist accessToken and refreshToken in SecureStore.
• Send Authorization: Bearer <accessToken> on authenticated calls.
• On 401, POST /v1/auth/refresh with { "refreshToken" }, store the new pair, retry once.

Access JWT TTL is 15 minutes (expiresIn). Customer refresh lasts 30 days.

Endpoints

Method	Path	Auth	Purpose
POST	/v1/auth/send-otp	Public	Send (or log) a one-time code
POST	/v1/auth/verify-otp	Public	Verify code; issue JWT pair
POST	/v1/auth/refresh	Public	Rotate access + refresh
POST	/v1/auth/logout	Public	Revoke the refresh token

Send OTP

Body

Field	Type	Notes
phone	string	4–24 characters

Example

POST /v1/auth/send-otp
Content-Type: application/json
Accept-Language: ar

{ "phone": "50000000" }

Results (inside the envelope)

Field	Notes
message	Localized acknowledgement
code	Present in non-production so the app can verify without SMS

SMS is stubbed: the server logs the code. Do not rely on a real SMS provider yet.

Verify OTP

Body

Field	Type
phone	string
code	string, 4–8 characters

POST /v1/auth/verify-otp
Content-Type: application/json

{ "phone": "50000000", "code": "1234" }

On success:

Field	Notes
customer	Public customer object
accessToken	JWT — send as Bearer
refreshToken	Opaque — store securely
tokenType	"Bearer"
expiresIn	Access TTL in seconds (900)

Guest cart (X-Cart-Token) and assistant conversations (X-Assistant-Guest) are merged onto the customer. After login you can drop those guest headers.

Refresh

POST /v1/auth/refresh
Content-Type: application/json

{ "refreshToken": "<opaque>" }

The previous refresh token is revoked. Persist the new accessToken + refreshToken.

Logout

POST /v1/auth/logout
Authorization: Bearer <accessToken>

Revokes refresh tokens for this customer. Delete the pair from SecureStore. If the access token is already expired, refresh first or just drop the local tokens and continue as a guest.

After login

Call GET /v1/account/me with Bearer. See Account.