Authentication

​

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.

Using the Anonymous Token: Include the received access_token as a Bearer token in the Authorization header for subsequent API calls, like fetching products:

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.

The Flow (Email/Phone/WhatsApp):

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
  }'

{
  "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
  }
}

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"
  }'

{
  "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..."
  }
}

Passwordless Login/Registration Flow Diagram:

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.

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.

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"
  }'

​

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.

Logout Flow Diagram:

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