Authentication verifies the identity of the user interacting with your storefront. Commerce Engine uses a robust token-based system (JWT) and offers flexible login methods, including passwordless options via Email, Phone, and WhatsApp.
Authorization
header of most API requests. It proves the userβs identity for a limited time.POST /auth/anonymous
(using the X-Api-Key
). These tokens allow basic browsing, cart management, and crucially, enable server-side analytics tracking from the start.X-Api-Key
in frontend code.POST /auth/anonymous
Authentication: Requires X-Api-Key
header.
Purpose:
user.id
to track the visitor immediately.access_token
and refresh_token
for the session.Anonymous Auth Flow
access_token
as a Bearer token in the Authorization
header for subsequent API calls, like fetching products:
register_if_not_exists
When initiating a login (POST /auth/login/*
), you can include the flag "register_if_not_exists": true
in the request body.POST /auth/login/email
(Body: { "email": "...", "register_if_not_exists": true }
)POST /auth/login/phone
(Body: { "phone": "...", "country_code": "+91", "register_if_not_exists": true }
)POST /auth/login/whatsapp
(Body: { "phone": "...", "country_code": "+91", "register_if_not_exists": true }
)Bearer
token.otp_token
: A temporary token associated with this specific OTP verification attempt.otp_action
: Confirms the context (usually login
or potentially register
).otp_token
back to Commerce Engine:POST /auth/verify-otp
Bearer
token.
access_token
and refresh_token
. These tokens are associated with the now logged-in user and have higher privileges than the initial anonymous tokens.user
object now contains the details of the logged-in user. is_anonymous
is false
, and is_logged_in
is true
.Passwordless Flow
register_if_not_exists
flow, their first_name
and last_name
might be null. You can allow them to update their profile later using:
PUT /auth/user/{id}
Bearer
token.{id}
is the user.id
obtained during login/verification.first_name
, last_name
). See the User
schema.POST /auth/generate-otp
): Useful if you need to trigger OTP generation outside the main login flow (e.g., verifying a phone number added to a profile). Specify the channel
(sms, email, whatsapp) and otp_action
(e.g., verify-phone
, update-email
). Requires a bearer token.POST /auth/verified-email-phone
): Check if specific emails or phone numbers are already marked as verified in the system. Requires a bearer token.POST /auth/login/password
): Allows login using email/phone and password. Returns new tokens on success. Requires a bearer token (can be anonymous).POST /auth/change-password
): For logged-in users to change their password. Requires old_password
, new_password
, confirm_password
. Requires a logged-in bearer token.POST /auth/forgot-password
): Initiates the password reset flow, sending an OTP. Requires email or phone. Requires a bearer token (can be anonymous). Responds with an otp_token
.POST /auth/reset-password
): Completes the password reset using the otp_token
from the forgot password flow and the new_password
. Requires a bearer token (can be anonymous). Returns new tokens on success.Secure Storage
Using Access Tokens
access_token
in the Authorization: Bearer <token>
header for all API calls (except POST /auth/anonymous
).Handling Expiry & Refreshing
exp
claim). Before it expires, use the refresh_token
to get a new pair of tokens.401 Unauthorized
error, it likely means the access token expired. Use the refresh_token
to get a new pair, then retry the original API call with the new access_token
.POST /auth/refresh-token
Bearer
token.Token Refresh Flow
POST /auth/refresh-token
). If that fails, or if you have no tokens stored, proceed to the next step.POST /auth/anonymous
again.Authorization: Bearer
header of the POST /auth/anonymous
request.
user_id
, and issues new anonymous access and refresh tokens linked to that same existing user_id
.Expired Token Recovery Flow
GET /auth/user/{id}
- Get full user details.PUT /auth/user/{id}
- Update name, etc.GET /auth/user/{id}/notification-preferences
- Retrieve current settings.POST /auth/user/{id}/notification-preferences
- Create initial preferences (if not set).PUT /auth/user/{id}/notification-preferences
- Update preferences (allow users to opt-in/out of transactional, promotional, newsletter emails/SMS/WhatsApp). See NotificationPreferences
schema.multipart/form-data
):
POST /auth/user/{id}/profile-image
- Add image.PUT /auth/user/{id}/profile-image
- Update image.DELETE /auth/user/{id}/profile-image
- Remove image.GET /auth/user/{id}/profile-image
- Retrieve image URL.PUT /auth/user/{id}/deactivate
- Mark the user account as inactive.POST /auth/logout
Bearer
token.200 OK
response containing:
user
object, now updated to reflect an anonymous state (is_anonymous: true
, is_logged_in: false
).access_token
and refresh_token
, linked to the same user_id
.access_token
and refresh_token
from storage.user
object provided in the logout response. This ensures your UI correctly reflects the now-anonymous status while retaining the underlying user_id
.user
object returned by Commerce Engine API responses (like Login, Verify OTP, Refresh Token, Update User, and Logout). Treat the user
object from CE as the source of truth for the userβs current status and details.Logout Flow