Authentication Overview
  • Tokens: Authentication relies on Access Tokens and Refresh Tokens.
    • Access Token: A short-lived Bearer token sent in the Authorization header of most API requests. It proves the user’s identity for a limited time.
    • Refresh Token: A longer-lived token used only to request a new Access Token when the current one expires. It should be stored securely and used less frequently.
  • User States:
    • Anonymous User: A user who hasn’t logged in or registered. They get tokens via 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.
    • Logged-in User: A user who has verified their identity via OTP (Email, Phone, WhatsApp) or potentially a password. They receive new, more privileged Access and Refresh tokens upon successful verification. These tokens grant access to sensitive endpoints like order history, address book, etc.
  • Security: Always transmit tokens over HTTPS. Store tokens securely on the client (e.g., HttpOnly cookies for web, secure storage for mobile).
    API Key SecurityNever expose your X-Api-Key in frontend code.

​
Anonymous Authentication

As shown in Getting Started, this is the first step for any new visitor to your storefront. Endpoint: POST /auth/anonymous Authentication: Requires X-Api-Key header. Purpose:
  1. Assigns a unique user.id to track the visitor immediately.
  2. Provides initial access_token and refresh_token for the session.
  3. Enables automatic server-side analytics event tracking for the user’s actions (viewing products, adding to cart, etc.) right from the start.

Anonymous Auth Flow

Using the Anonymous Token: Include the received access_token as a Bearer token in the Authorization header for subsequent API calls, like fetching products:
Using Anonymous Token
curl GET /catalog/products \
  --header 'Authorization: Bearer ANONYMOUS_ACCESS_TOKEN'

​
Passwordless Login & Registration

Commerce Engine prioritizes frictionless login experiences using One-Time Passwords (OTPs) sent via Email, Phone, or WhatsApp. This flow also seamlessly handles registration for new users.
Key Feature: register_if_not_existsWhen initiating a login (POST /auth/login/*), you can include the flag "register_if_not_exists": true in the request body.
  • If the user exists: An OTP is sent for login verification.
  • If the user does not exist: Commerce Engine automatically creates a basic user record associated with the provided email/phone and sends an OTP for verification and implicit registration.
This eliminates the need for users to guess if they have an account and removes the requirement for separate “Login” vs. “Sign Up” flows or distinct “Guest Checkout” paths. Every user starts the same way.
The Flow (Email/Phone/WhatsApp):
1

Initiate Login

The user provides their email address, phone number, or WhatsApp number. Your application calls the corresponding login endpoint:
  • 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 })
Authentication: Requires a valid (anonymous or logged-in) Bearer token.
Initiate Email Login Example
curl -X POST 'YOUR_BASE_URL/auth/login/email' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "register_if_not_exists": true
  }'
2

Receive OTP Token

Commerce Engine sends an OTP to the specified channel and responds to your app with:
Initiate Login Response
{
  "message": "OTP sent successfully.",
  "success": true,
  "content": {
    "otp_token": "a_temporary_token_representing_this_otp_attempt",
    "otp_action": "login" // Or "register" if register_if_not_exists triggered creation
  }
}
  • otp_token: A temporary token associated with this specific OTP verification attempt.
  • otp_action: Confirms the context (usually login or potentially register).
3

User Enters OTP

Display an input field for the user to enter the OTP they received.
4

Verify OTP

Send the user-entered OTP and the otp_token back to Commerce Engine:
  • Endpoint: POST /auth/verify-otp
  • Authentication: Requires a valid (anonymous or logged-in) Bearer token.
  • Body:
    Verify OTP Request Body
    {
  "otp": "USER_ENTERED_OTP",
  "otp_token": "the_otp_token_received_in_step_2",
  "otp_action": "login" // From step 2
}
Verify OTP Example
curl -X POST 'YOUR_BASE_URL/auth/verify-otp' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "otp": "123456",
    "otp_token": "the_otp_token_received_in_step_2",
    "otp_action": "login"
  }'
5

Login Success & New Tokens

If the OTP is correct, Commerce Engine verifies the user (or completes the registration) and responds with:
Verify OTP Success Response
{
  "message": "OTP verified successfully. User logged in.",
  "success": true,
  "content": {
    "user": {
      "id": "01HXXXXXXLOGGEDINUSERID",
      "first_name": "...", // May be null if just registered
      "last_name": "...",  // May be null if just registered
      "email": "[email protected]",
      "is_email_verified": true,
      "phone": "9988776655",
      "country_code": "+91",
      "is_phone_verified": true,
      "profile_image_url": null,
      "is_anonymous": false,
      "is_logged_in": true,
      "login_methods": ["email", "phone"],
      // ... other user details
    },
    "access_token": "NEW_PRIVILEGED_ACCESS_TOKEN_eyJ...",
    "refresh_token": "NEW_PRIVILEGED_REFRESH_TOKEN_abc..."
  }
}
Important: Update Tokens
  • Crucially: You receive a new access_token and refresh_token. These tokens are associated with the now logged-in user and have higher privileges than the initial anonymous tokens.
  • Replace the old (anonymous) tokens in your secure storage with these new ones.
  • The user object now contains the details of the logged-in user. is_anonymous is false, and is_logged_in is true.
Passwordless Login/Registration Flow Diagram:

Passwordless Flow

Updating User Profile: If a user signs up using only their email/phone via the register_if_not_exists flow, their first_name and last_name might be null. You can allow them to update their profile later using:
  • Endpoint: PUT /auth/user/{id}
  • Authentication: Requires a logged-in user’s Bearer token.
  • Path Parameter: {id} is the user.id obtained during login/verification.
  • Request Body: Send the fields to update (e.g., first_name, last_name). See the User schema.
Update User Profile Example
curl -X PUT \
  'https://staging.api.commercengine.io/api/v1/YOUR_STORE_ID/storefront/auth/user/USER_ID' \
  --header 'Authorization: Bearer LOGGED_IN_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Rajesh",
    "last_name": "Kumar"
  }'

​
Other Authentication Endpoints

While passwordless is recommended, Commerce Engine provides other endpoints for different scenarios:
  • Generate OTP (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.
  • Check Verification Status (POST /auth/verified-email-phone): Check if specific emails or phone numbers are already marked as verified in the system. Requires a bearer token.
  • Password Login (POST /auth/login/password): Allows login using email/phone and password. Returns new tokens on success. Requires a bearer token (can be anonymous).
  • Change Password (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.
  • Forgot Password (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.
  • Reset Password (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.

​
Token Management

Properly managing Access and Refresh tokens is vital for security and user experience.
1

Secure Storage

Security Best Practices
  • Web: Store tokens securely. HttpOnly cookies are often recommended as they are not accessible via client-side JavaScript, mitigating XSS risks. Alternatively, use browser storage (localStorage/sessionStorage) but be mindful of XSS vulnerabilities.
  • Mobile: Use the platform’s secure storage mechanisms (Keychain on iOS, Keystore/EncryptedSharedPreferences on Android).
  • Never store tokens insecurely (e.g., plain localStorage without XSS protection).
2

Using Access Tokens

Include the access_token in the Authorization: Bearer <token> header for all API calls (except POST /auth/anonymous).
3

Handling Expiry & Refreshing

Access tokens are short-lived (e.g., 15 minutes, 1 hour - the exact duration is configured in Commerce Engine).
  • Proactive Refresh: Decode the access token (the payload is not encrypted) to check its expiry time (exp claim). Before it expires, use the refresh_token to get a new pair of tokens.
  • Reactive Refresh: If an API call returns a 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.
  • Refresh Endpoint: POST /auth/refresh-token
  • Authentication: Requires a valid (anonymous or logged-in) Bearer token.
  • Request Body:
    Refresh Token Request Body
    { "refresh_token": "YOUR_STORED_REFRESH_TOKEN" }
  • Response (Success):
    Refresh Token Success Response
    {
  "message": "Token refreshed successfully.",
  "success": true,
  "content": {
    "access_token": "NEW_ACCESS_TOKEN_xyz...",
    "refresh_token": "POSSIBLY_NEW_REFRESH_TOKEN_123..." // Refresh tokens might rotate
  }
}
  • Update Storage: Replace the old tokens with the new ones received from the refresh endpoint.
  • Refresh Token Failure: If the refresh token itself is invalid or expired, the user must log in again.
Token Refresh Flow Diagram:

Token Refresh Flow

Refresh Token Example
curl -X POST 'YOUR_BASE_URL/auth/refresh-token' \
  --header 'Authorization: Bearer ANY_VALID_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "refresh_token": "YOUR_STORED_REFRESH_TOKEN"
  }'

​
Handling Expired Refresh Tokens (Long User Absence)

What happens if a user returns to your app after a long time, and both their access token and refresh token have expired? Attempting to use the refresh token will fail.
Best Practice: Handling Long Absences
  1. On App Load: Always attempt to validate the user’s session. A common way is to try refreshing the token immediately (POST /auth/refresh-token). If that fails, or if you have no tokens stored, proceed to the next step.
  2. Re-authenticate Anonymously: Call POST /auth/anonymous again.
  3. Preserve User ID: To ensure continuity for analytics and user history, include the expired access token (if you still have it) in the Authorization: Bearer header of the POST /auth/anonymous request.
    • Commerce Engine intelligently recognizes the expired token, finds the associated user_id, and issues new anonymous access and refresh tokens linked to that same existing user_id.
    • If no expired token is sent, a completely new anonymous user ID and tokens will be generated.
Expired Token Recovery Flow:

Expired Token Recovery Flow

This ensures that even after long absences, user activity remains tied to their original profile, providing valuable insights and enabling personalization upon eventual login.

​
User Management & Preferences

Once a user is logged in, you can manage their profile and preferences:
  • Retrieve User: GET /auth/user/{id} - Get full user details.
  • Update User: PUT /auth/user/{id} - Update name, etc.
  • Notification Preferences:
    • 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.
  • Profile Image: Manage user profile images (Requires 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.
  • Deactivate Account: PUT /auth/user/{id}/deactivate - Mark the user account as inactive.

​
Logout

To log a user out, you invalidate their current session tokens server-side and clear them client-side.
  • Endpoint: POST /auth/logout
  • Authentication: Requires a valid logged-in user’s Bearer token.
  • Action: Commerce Engine invalidates the associated refresh token server-side.
  • Response: The API returns a 200 OK response containing:
    • The user object, now updated to reflect an anonymous state (is_anonymous: true, is_logged_in: false).
    • A new set of anonymous access_token and refresh_token, linked to the same user_id.
  • Client-Side Action:
    1. Clear Old Tokens: Securely remove the previous (logged-in) access_token and refresh_token from storage.
    2. Store New Anonymous Tokens: Store the new anonymous tokens received in the response.
    3. Update Local State: Crucially, update your application’s local user state (e.g., in your state management library) using the user object provided in the logout response. This ensures your UI correctly reflects the now-anonymous status while retaining the underlying user_id.
State Management Best PracticeTo simplify client-side state management and avoid conflicts, always update your local user state object based on the 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 Diagram:

Logout Flow

Logout Example
curl -X POST 'YOUR_BASE_URL/auth/logout' \
  --header 'Authorization: Bearer LOGGED_IN_ACCESS_TOKEN'