Skip to main content

Customer Auth

The customer auth endpoints manage the customer's session within the theme. This is separate from the API key, which authenticates your theme (the application).

See Customer Auth Flow for the full implementation guide.

Request OTP (login)​

POST /access/api/v1/auth

Sends a 6-digit OTP to the customer's email and returns a verification id to use in the verify step.

Request body:

{ "email": "customer@example.com" }

Response:

{
  "status": "verify",
  "message": "Please verify to continue",
  "data": { "id": "69e885ba4f0e4f248bc572fe" }
}

Note: the status is "verify", not "success". Store data.id and the email — both are required in the next step.

Possible errors: EMAIL_REQUIRED, ACCOUNT_NOT_FOUND, ACCOUNT_BLACKLISTED, TOO_MANY_LOGIN_ATTEMPTS, AUTH_NOT_INITIALIZED

Verify OTP​

POST /access/api/v1/auth/verify

Request body:

{
  "email": "customer@example.com",
  "id": "69e885ba4f0e4f248bc572fe",
  "code": "217273",
  "event": "login"
}

Response:

{
  "status": "success",
  "token": "eyJhbGci..."
}

Store the token in localStorage (or a cookie). Pass it as Authorization: Bearer <token> on all authenticated requests.

Possible errors: INVALID_CODE, VERIFICATION_NOT_VALID, VERIFICATION_NOT_FOUND, VERIFICATION_USER_MISMATCH, TOO_MANY_VERIFY_ATTEMPTS

POST /access/api/v1/auth/access

Logs in a customer using a link from a transactional email (e.g. order confirmation). No OTP required.

Request body:

{
  "id": "link_id",
  "email": "customer@example.com",
  "order": "order_id"
}

Response: Same as Verify OTP — { "status": "success", "token": "eyJhbGci..." }

Possible errors: INVALID_ACCESS_LINK, ACCESS_LINK_EXPIRED, ORDER_CANCELLED, ORDER_HAS_REFUND

Get current customer​

GET /access/api/v1/auth

Requires customer JWT.

Headers:

Authorization: Bearer <customer_token>

Response:

{
  "status": "success",
  "data": {
    "user": {
      "_id": "69e885ba4f0e4f248bc572fe",
      "name": "Jane Doe",
      "email": "customer@example.com",
      "phone": "0712345678",
      "date": "2026-01-15T08:00:00.000Z",
      "lastLogin": "2026-04-22T10:30:00.000Z"
    },
    "shipping": {
      "_id": "...",
      "town": "Nairobi",
      "city": "Westlands",
      "apartment": "Apex Towers",
      "room": "4B",
      "postalCode": ""
    }
  }
}

shipping is null if the customer has not saved an address.

Possible errors: AUTH_TOKEN_MISSING, AUTH_TOKEN_INVALID, AUTH_TOKEN_DEVICE_MISMATCH, SESSION_EXPIRED, AUTH_USER_NOT_FOUND, ACCOUNT_BLACKLISTED, ACCOUNT_INACTIVE

Update customer profile​

PATCH /access/api/v1/auth

Requires customer JWT.

Headers:

Authorization: Bearer <customer_token>

Request body:

{
  "name": "Jane Doe",
  "phone": "0712345678",
  "town": "Nairobi",
  "city": "",
  "apartment": "Westlands",
  "room": "4B",
  "postalCode": ""
}

name, phone, and town are required.

Response: Same shape as Get current customer.

Possible errors: PHONE_NUMBER_INVALID, AUTH_TOKEN_MISSING, AUTH_TOKEN_INVALID, SESSION_EXPIRED