POST /api/v3/login — User Login and Access Token

This endpoint authenticates a user with their email or mobile number and password and returns a Bearer access token along with user state information (verification status, missing profile data, cart count, role, and approval status). Use it as the entry point for any client that needs to make authenticated API calls.

Endpoint

POST /api/v3/login

Required role: None (public endpoint). Parent accounts are not permitted.

Required Headers

Header	Value
`Accept`	`application/json`
`Content-Type`	`application/json`

Optional Headers

Header	Type	Description
`device_type`	`string`	Device category — for example `web`, `app`, or `desktop`. Used to enforce per-device-type limits.
`device_token`	`string`	Unique identifier for the user’s device. May also be sent in the request body.
`device-name`	`string`	Friendly name of the device (for example `iPhone 13`). May also be sent in the request body.

The system auto-resolves device information from the request body or the headers. If neither is provided and the request comes from a web client, a UUID is generated and tracked on the server.

Request Body

string

required

The user’s email address or mobile number.

string

required

The user’s password.

string

Unique token for the device. Can also be passed as the device_token header.

string

Descriptive name for the device. Can also be passed as the device-name header.

Example Request

curl -X POST https://app.example.com/api/v3/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secretpassword",
    "device_token": "fcm-token-xyz123",
    "device_name": "Samsung Galaxy S22"
  }'

Response

200 OK

Returns the Bearer access token and a set of user state flags. Use the access_token value in the Authorization: Bearer <token> header on subsequent requests.

{
  "token_type": "Bearer",
  "expires_in": 1700000000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "ss_record": 0,
  "missed_data": false,
  "array_of_missing_data": [],
  "change_password": true,
  "cart_items": 3,
  "is_verified": true,
  "is_verified_mobile": true,
  "data": 150,
  "mobile": "+1234567890",
  "role": "user",
  "is_approved": true
}

Response fields:

Field	Type	Description
`token_type`	`string`	Always `Bearer`.
`access_token`	`string`	The Bearer token to send in the `Authorization` header on subsequent requests.
`expires_in`	`integer`	Token expiration as a Unix timestamp.
`ss_record`	`integer`	Internal session record identifier.
`missed_data`	`boolean`	`true` if the user profile is missing required fields.
`array_of_missing_data`	`string[]`	List of profile fields the user still needs to fill out. Empty when `missed_data` is `false`.
`change_password`	`boolean`	`true` if the user was logged in via OTP and must change their password.
`cart_items`	`integer`	Number of items currently in the user’s cart.
`is_verified`	`boolean`	Whether the user account is verified.
`is_verified_mobile`	`boolean`	Whether the user’s mobile number has been verified via SMS.
`data`	`integer`	The authenticated user’s ID.
`mobile`	`string`	The user’s mobile number in international format.
`role`	`string`	The user’s role — for example `user` or `instructor`.
`is_approved`	`boolean`	Whether the account has been approved by an admin.

Validation Error Responses (422)

The API returns a 422 status when required fields are missing or malformed.

{
  "message": "The email field is required."
}

Error Responses

Status	Message	Cause
`400`	`You are not allowed to use more than one account per device.`	Device restrictions forbid using multiple accounts on a single device.
`401`	`These credentials do not match our records.`	The email/mobile or password is incorrect.
`401`	`Parent login not allowed.`	Parent accounts cannot authenticate through this endpoint.
`401`	`Blocked User`	The account has been blocked by an admin.
`401`	`Your device has been disabled, please contact admin.`	The device is disabled and cannot be used to sign in.
`401`	`You have reached the maximum number of devices allowed for login.`	The account has hit its device limit. Similar variants exist for web, desktop, and app-specific limits.
`422`	Field-specific message	Required fields are missing or malformed.

Send device_type, device_token, and device-name on every login so device limits and per-device restrictions are enforced accurately. If you omit them from a web request, the server assigns a UUID for tracking.

homework

quizzes

course

POST /api/v3/login — User Login and Access Token

Endpoint

Required Headers

Optional Headers

Request Body

Example Request

Response

200 OK

Validation Error Responses (422)

Error Responses

​Endpoint

​Required Headers

​Optional Headers

​Request Body

​Example Request

​Response

​200 OK

​Validation Error Responses (422)

​Error Responses

Endpoint

Required Headers

Optional Headers

Request Body

Example Request

Response

200 OK

Validation Error Responses (422)

Error Responses