> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vclasses.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Authenticate a user with email or mobile and password to receive a Bearer access token and user state flags including verification, missing data, and role.

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

```text theme={null}
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.      |

<Note>
  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.
</Note>

## Request Body

<ParamField body="email" type="string" required>
  The user's email address or mobile number.
</ParamField>

<ParamField body="password" type="string" required>
  The user's password.
</ParamField>

<ParamField body="device_token" type="string">
  Unique token for the device. Can also be passed as the `device_token` header.
</ParamField>

<ParamField body="device_name" type="string">
  Descriptive name for the device. Can also be passed as the `device-name` header.
</ParamField>

## Example Request

```bash theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.                                                               |

<Tip>
  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.
</Tip>