> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> 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.
**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 Security**
The `X-Api-Key` is a publishable key and so it is fine for you to include it in your 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.
**Using the Anonymous Token:** Include the received `access_token` as a Bearer token in the `Authorization` header for subsequent API calls, like fetching products:
```bash Using Anonymous Token theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl GET /catalog/products \
--header 'Authorization: Bearer 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 login flow is the recommended way to implement checkout when building storefronts, especially for brands selling physical goods that need to be shipped. Having a validated email/phone early in the checkout flow reduce overall friction, minimize RTOs due to incorrect contact details and make it easier for your customers to access protected endpoints like Order Details after an order is successfully placed.
**Key Feature: `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.
* **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):**
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.
```bash Initiate Email Login Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'YOUR_BASE_URL/auth/login/email' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"email": "user@example.com",
"register_if_not_exists": true
}'
```
Commerce Engine sends an OTP to the specified channel and responds to your app with:
```json Initiate Login Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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`).
Display an input field for the user to enter the OTP they received.
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:**
```json Verify OTP Request Body theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"otp": "USER_ENTERED_OTP",
"otp_token": "the_otp_token_received_in_step_2",
"otp_action": "login" // From step 2
}
```
```bash Verify OTP Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
}'
```
If the OTP is correct, Commerce Engine verifies the user (or completes the registration) and responds with:
```json Verify OTP Success Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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": "user@example.com",
"is_email_verified": true,
"phone": "9988776655",
"country_code": "+91",
"is_phone_verified": true,
"profile_image_url": null,
"is_anonymous": false,
"is_logged_in": true, // Use this key to create auth guards or protected routes
"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:**
**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.
```bash Update User Profile Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
}'
```
When a new user adds an address, their first and last name will be
automatically updated.
### 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.
**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).**
Include the `access_token` in the `Authorization: Bearer ` header for all API calls (except `POST /auth/anonymous`).
Access tokens are short lived Json Web Tokens (JWTs).
* **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:**
```json Refresh Token Request Body theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "refresh_token": "YOUR_STORED_REFRESH_TOKEN" }
```
* **Response (Success):**
```json Refresh Token Success Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:**
```bash Refresh Token Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:**
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 Practice**
To 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:**
```bash Logout Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'YOUR_BASE_URL/auth/logout' \
--header 'Authorization: Bearer LOGGED_IN_ACCESS_TOKEN'
```