> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> API reference for Essal Access user management — create, update, activate, deactivate, and manage users.

## List Users

`GET /v1/access/users`

**Query Parameters**

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `status`  | enum    | `active`, `suspended`, `pending`         |
| `role`    | string  | Filter users with a specific role        |
| `limit`   | integer | Results per page (default: 20, max: 100) |

***

## Get a User

`GET /v1/access/users/{id}`

Returns a full user profile including roles, groups, and last session info.

***

## Create a User

`POST /v1/access/users`

```json theme={null}
{
  "email": "jane.doe@example.com",
  "display_name": "Jane Doe",
  "roles": ["office:editor", "project:member"],
  "send_invite": true
}
```

**Response** — `201 Created`

```json theme={null}
{
  "id": "usr_01HXYZ1234",
  "email": "jane.doe@example.com",
  "display_name": "Jane Doe",
  "status": "pending",
  "created_at": "2026-07-10T09:00:00Z"
}
```

***

## Update a User

`PATCH /v1/access/users/{id}`

```json theme={null}
{
  "display_name": "Jane Smith",
  "roles": ["office:admin", "project:member", "sales:viewer"]
}
```

***

## Deactivate a User

`POST /v1/access/users/{id}/deactivate`

Suspends the user, revokes all active sessions, and removes app access. Data is preserved.

**Response** — `200 OK`

***

## Reset Password

`POST /v1/access/users/{id}/password-reset`

Sends a password reset email to the user's registered email address.

***

## Delete a User

`DELETE /v1/access/users/{id}`

Permanently deletes the user and anonymises their authored content. This action is irreversible.

<Warning>
  Hard deletion removes the user's personal data in compliance with data retention policies. Content they created (documents, tasks, notes) is preserved but re-attributed to a placeholder identity.
</Warning>