OTP Authentication Flow - RMZ Developer Docs

The Storefront API uses OTP-based authentication. Customers receive a 4-digit verification code via SMS or email, verify it, and receive a Bearer token for authenticated requests.

Flow Overview

Start — Send phone number or email to receive an OTP code
Verify — Submit the OTP code to verify identity
Complete — (New customers only) Provide name and email to finish registration

POST /auth/start

Start an authentication session. Auto-detects the type based on provided fields.

Authentication

None required (guest endpoint).

Request

Headers

Header	Value	Required
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
country_code	numeric	Yes (phone auth)	Country dial code (1-999, e.g., `966`)
phone	string	Yes (phone auth)	Phone number without country code (digits only)
email	string	Yes (email auth)	Customer email address

Provide either country_code + phone for phone authentication, or email for email authentication. The API auto-detects which flow to use.

Example Request

curl -X POST "https://front.rmz.gg/api/auth/start" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "966",
    "phone": "501234567"
  }'

const response = await fetch("https://front.rmz.gg/api/auth/start", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    country_code: "966",
    phone: "501234567"
  })
});
const data = await response.json();

import requests

response = requests.post("https://front.rmz.gg/api/auth/start", json={
    "country_code": "966",
    "phone": "501234567"
})
data = response.json()

$response = Http::post("https://front.rmz.gg/api/auth/start", [
    "country_code" => "966",
    "phone" => "501234567"
]);
$data = $response->json();

Response

Success (200)

{
  "success": true,
  "data": {
    "session_token": "auth_abc123xyz"
  },
  "message": "Verification code sent successfully"
}

Error Responses

Status	Message	Description
422	(validation errors)	Missing or invalid phone/email fields
429	Too many authentication attempts today. Please try again tomorrow	50 sessions/day per IP exceeded
429	Too many authentication attempts for this phone number today	10 sessions/day per phone number exceeded
500	Store not found in context	Store could not be resolved

POST /auth/phone/start

Dedicated phone authentication endpoint. Behaves identically to POST /auth/start with phone parameters but enforces phone-specific validation.

Body Parameters

Parameter	Type	Required	Description
country_code	numeric	Yes	Country dial code (1-999)
phone	string	Yes	Phone number (digits only)

POST /auth/initiate

Legacy authentication endpoint. Accepts a type field and nested data object instead of top-level fields.

Authentication

None required (guest endpoint).

Body Parameters

Parameter	Type	Required	Description
type	string	Yes	Authentication type. Currently only `phone` is supported
data.country	string	Yes (phone)	Country dial code (must be a supported Arab country code)
data.phone	string	Yes (phone)	Phone number (6-12 digits)
data.email	string	Yes (email)	Customer email address

Response

Same as POST /auth/start.

This is a legacy endpoint maintained for backward compatibility. New integrations should use POST /auth/start instead.

POST /auth/verify

Verify the OTP code sent to the customer’s phone or email.

Authentication

None required (guest endpoint).

Request

Headers

Header	Value	Required
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
session_token	string	No	Session token from the start step
code	integer	Yes	The 4-digit OTP code
otp	integer	No	Alias for `code` (backward compatibility)

Example Request

curl -X POST "https://front.rmz.gg/api/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "auth_abc123xyz",
    "code": 1234
  }'

const response = await fetch("https://front.rmz.gg/api/auth/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    session_token: "auth_abc123xyz",
    code: 1234
  })
});
const data = await response.json();

response = requests.post("https://front.rmz.gg/api/auth/verify", json={
    "session_token": "auth_abc123xyz",
    "code": 1234
})
data = response.json()

$response = Http::post("https://front.rmz.gg/api/auth/verify", [
    "session_token" => "auth_abc123xyz",
    "code" => 1234
]);
$data = $response->json();

Response

Existing Customer (200)

When the customer already exists in this store:

{
  "success": true,
  "data": {
    "type": "authenticated",
    "token": "1|abc123xyz...",
    "cart_token": "cart_xyz789",
    "customer": {
      "id": 123,
      "first_name": "Ahmed",
      "last_name": "Ali",
      "email": "ahmed@example.com",
      "phone": "501234567",
      "country_code": "966"
    }
  },
  "message": "Authentication successful"
}

Customer From Another Store (200)

When the customer exists in another store but not in this one, a new customer record is automatically created for this store:

{
  "success": true,
  "data": {
    "type": "new_customer",
    "token": "1|abc123xyz...",
    "cart_token": "cart_xyz789",
    "customer": {
      "id": 456,
      "first_name": "Ahmed",
      "last_name": "Ali",
      "email": "ahmed@example.com",
      "phone": "501234567",
      "country_code": "966"
    }
  },
  "message": "Authentication successful"
}

The type field can be either "authenticated" (existing customer in this store) or "new_customer" (auto-created from another store). Both cases return a token and the customer can proceed immediately.

New Customer (200)

When the phone/email is not registered in any store, the response indicates registration is required:

{
  "success": true,
  "data": {
    "type": "new",
    "requires_registration": true,
    "session_token": "auth_abc123xyz"
  },
  "message": "Please complete your registration"
}

When requires_registration is true, you must call POST /auth/complete to finish creating the customer account.

Error Responses

Status	Message	Description
400	Please restart the authentication process	Invalid or missing session
400	Verification code expired. Please restart the process	Session has expired
400	Too many failed attempts. Please restart the process	Max verification attempts reached
400	Invalid verification code	Wrong OTP code
429	Too many verification attempts. Please wait before trying again	Rate limit exceeded (5 attempts/min per IP)
429	Please wait seconds before trying again	Progressive cooldown active

POST /auth/phone/verify

Dedicated phone verification endpoint. Behaves identically to POST /auth/verify.

POST /auth/resend

Resend the OTP code for an active session.

Authentication

None required (guest endpoint).

Request

Body Parameters

Parameter	Type	Required	Description
session_token	string	Yes	Session token from the start step

Example Request

curl -X POST "https://front.rmz.gg/api/auth/resend" \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "auth_abc123xyz"
  }'

const response = await fetch("https://front.rmz.gg/api/auth/resend", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ session_token: "auth_abc123xyz" })
});

response = requests.post("https://front.rmz.gg/api/auth/resend", json={
    "session_token": "auth_abc123xyz"
})

$response = Http::post("https://front.rmz.gg/api/auth/resend", [
    "session_token" => "auth_abc123xyz"
]);

Response

Success (200)

{
  "success": true,
  "data": {
    "session_token": "auth_abc123xyz"
  },
  "message": "Verification code sent successfully"
}

Error Responses

Status	Message	Description
400	Invalid session. Please restart the authentication process	Session token not found
400	Session expired. Please restart the authentication process	Session has expired
429	Please wait 30 seconds before requesting a new code	Must wait 30 seconds between resends
429	Too many resend attempts. Please wait before trying again	3 resends per 10 minutes exceeded

POST /auth/phone/resend

Dedicated phone resend endpoint. Behaves identically to POST /auth/resend.

POST /auth/complete

Complete registration for new customers after OTP verification.

Authentication

None required (guest endpoint). Requires a verified session token.

Request

Body Parameters

Parameter	Type	Required	Description
session_token	string	Yes	Verified session token
email	string	Yes	Customer email (must be unique per store)
firstName	string	Yes	Customer first name
lastName	string	Yes	Customer last name

Example Request

curl -X POST "https://front.rmz.gg/api/auth/complete" \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "auth_abc123xyz",
    "email": "ahmed@example.com",
    "firstName": "Ahmed",
    "lastName": "Ali"
  }'

const response = await fetch("https://front.rmz.gg/api/auth/complete", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    session_token: "auth_abc123xyz",
    email: "ahmed@example.com",
    firstName: "Ahmed",
    lastName: "Ali"
  })
});
const data = await response.json();

response = requests.post("https://front.rmz.gg/api/auth/complete", json={
    "session_token": "auth_abc123xyz",
    "email": "ahmed@example.com",
    "firstName": "Ahmed",
    "lastName": "Ali"
})
data = response.json()

$response = Http::post("https://front.rmz.gg/api/auth/complete", [
    "session_token" => "auth_abc123xyz",
    "email" => "ahmed@example.com",
    "firstName" => "Ahmed",
    "lastName" => "Ali"
]);
$data = $response->json();

Response

Success (200)

{
  "success": true,
  "data": {
    "type": "registered",
    "token": "1|abc123xyz...",
    "customer": {
      "id": 456,
      "first_name": "Ahmed",
      "last_name": "Ali",
      "email": "ahmed@example.com",
      "phone": "501234567",
      "country_code": "966"
    }
  },
  "message": "Account created and authenticated successfully"
}

Error Responses

Status	Message	Description
400	Please restart the authentication process	Session not found, not verified, or not eligible for registration
400	Session expired. Please restart the process	Session has expired
400	Customer already exists. Please login with existing credentials	Customer record already exists for this store
422	(validation errors)	Email already in use in this store, or missing required fields

Rate Limits Summary

Action	Limit	Window
Start authentication	50 per IP	24 hours
Phone-specific start	10 per phone number	24 hours
Verify OTP	5 per IP	1 minute
Resend OTP	3 per identifier	10 minutes
Resend cooldown	1 per session	30 seconds

Session Expiry

OTP sessions expire after 5 minutes. Expired sessions are automatically cleaned up. If a session expires, the customer must restart the authentication flow from POST /auth/start.

​Flow Overview

​POST /auth/start

​Authentication

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (200)

​Error Responses

​POST /auth/phone/start

​Body Parameters

​POST /auth/initiate

​Authentication

​Body Parameters

​Response

​POST /auth/verify

​Authentication

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Existing Customer (200)

​Customer From Another Store (200)

​New Customer (200)

​Error Responses

​POST /auth/phone/verify

​POST /auth/resend

​Authentication

​Request

​Body Parameters

​Example Request

​Response

​Success (200)

​Error Responses

​POST /auth/phone/resend

​POST /auth/complete

​Authentication

​Request

​Body Parameters

​Example Request

​Response

​Success (200)

​Error Responses

​Rate Limits Summary

​Session Expiry

Flow Overview

POST /auth/start

Authentication

Request

Headers

Body Parameters

Example Request

Response

Success (200)

Error Responses

POST /auth/phone/start

Body Parameters

POST /auth/initiate

Authentication

Body Parameters

Response

POST /auth/verify

Authentication

Request

Headers

Body Parameters

Example Request

Response

Existing Customer (200)

Customer From Another Store (200)

New Customer (200)

Error Responses

POST /auth/phone/verify

POST /auth/resend

Authentication

Request

Body Parameters

Example Request

Response

Success (200)

Error Responses

POST /auth/phone/resend

POST /auth/complete

Authentication

Request

Body Parameters

Example Request

Response

Success (200)

Error Responses

Rate Limits Summary

Session Expiry