> ## 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/dashboard/v1/users/change-password — Admin Change User Password

> Allow tenant administrators to reset or change any user's password using their email, mobile number, student code, or national ID.

This endpoint allows an authorized administrator to change the password for any user account in the tenant (students, instructors, or parents). The target user can be resolved flexibly using any of the four supported identity attributes (`email`, `mobile`, `code`, or `national_id`), or via a single unified `identifier` field.

Upon a successful password change, the user's password hash is updated, all temporary OTP and PIN codes are cleared, and active OAuth access tokens are revoked for security.

## Endpoint

```text theme={null}
POST /api/dashboard/v1/users/change-password
```

**Required role:** `admin` (or an authenticated user with `edit users` permission).

## Required Headers

| Header | Value | Description |
| - | - | - |
| `Authorization` | `Bearer <admin_token>` | Admin Bearer authentication token. |
| `Accept` | `application/json` | Required to receive JSON responses. |
| `Content-Type` | `application/json` | Request payload format. |

<Note>
  **Flexible User Lookup:** You can identify the target user either by providing explicit fields (`email`, `mobile`, `code`, `national_id`) OR by passing a single `identifier` parameter that automatically matches across all four fields. At least one identifier must be provided.
</Note>

## Request Body

<ParamField body="password" type="string" required>
  The new password for the user account (minimum 6 characters).
</ParamField>

<ParamField body="password_confirmation" type="string">
  Optional confirmation that must match `password` when provided.
</ParamField>

<ParamField body="identifier" type="string">
  Unified search string. Matches against `email`, `mobile`, `code`, or `national_id`.
</ParamField>

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

<ParamField body="mobile" type="string">
  The user's mobile / phone number.
</ParamField>

<ParamField body="code" type="string">
  The user's student or system code (e.g., `STU-1024`).
</ParamField>

<ParamField body="national_id" type="string">
  The user's national identity number (e.g., 14-digit Egyptian national ID).
</ParamField>

## Example Requests

### 1. Using the Unified Identifier

```bash theme={null}
curl -X POST https://your-academy.vclasses.net/api/dashboard/v1/users/change-password \
  -H "Authorization: Bearer <admin_token>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "01001234567",
    "password": "NewSecretPassword123!"
  }'
```

### 2. Using National ID

```bash theme={null}
curl -X POST https://your-academy.vclasses.net/api/dashboard/v1/users/change-password \
  -H "Authorization: Bearer <admin_token>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "national_id": "29801011234567",
    "password": "NewSecretPassword123!",
    "password_confirmation": "NewSecretPassword123!"
  }'
```

### 3. Using Student Code

```bash theme={null}
curl -X POST https://your-academy.vclasses.net/api/dashboard/v1/users/change-password \
  -H "Authorization: Bearer <admin_token>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "STU-8821",
    "password": "NewSecretPassword123!"
  }'
```

## Response

### 200 OK

Returns success confirmation and the resolved user summary details.

```json theme={null}
{
  "status": "success",
  "message": "User password updated successfully",
  "data": {
    "user_id": 45,
    "name": "Ahmed Mohamed",
    "email": "ahmed@example.com",
    "mobile": "01001234567",
    "code": "STU-8821",
    "national_id": "29801011234567"
  }
}
```

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Status of the operation (`success` or `error`). |
| `message` | `string` | Localized success message. |
| `data.user_id` | `integer` | The unique ID of the target user. |
| `data.name` | `string` | Full name of the target user (`fname` + `lname`). |
| `data.email` | `string` | User email address. |
| `data.mobile` | `string` | User mobile number. |
| `data.code` | `string` | Student / account code. |
| `data.national_id` | `string` | User national ID. |

### Validation Error Response (422)

Returned when required parameters are missing or invalid (e.g. no identifier passed or password is too short).

```json theme={null}
{
  "status": "error",
  "message": "At least one identifier must be provided.",
  "errors": {
    "identifier": [
      "At least one identifier must be provided."
    ]
  }
}
```

### Not Found Response (404)

Returned when no user in the current tenant matches any of the provided identifiers.

```json theme={null}
{
  "status": "error",
  "message": "User not found"
}
```

## Error Responses

| Status | Message | Cause |
| - | - | - |
| `401` | `UnauthorizedRequest` | Missing or invalid admin Bearer token. |
| `403` | `Unauthorized` | The authenticated user does not have administrative privileges (`role != 'admin'`). |
| `404` | `User not found` | No user found matching the provided email, mobile, code, or national ID. |
| `422` | `At least one identifier must be provided.` | Neither `identifier`, `email`, `mobile`, `code`, nor `national_id` was supplied. |
| `422` | `The password must be at least 6 characters.` | Password length does not meet the minimum requirement. |

<Tip>
  **Session Security:** When an administrator changes a user's password, all active Passport access tokens (`oauth_access_tokens`) for that user are immediately revoked, preventing compromised devices or unauthorized active sessions from remaining logged in.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.