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

# Users over the API

> Everything a headless integration needs to manage the people in a workspace: who exists (to assign work), add a colleague, deactivate one, change a role.

Everything a headless integration needs to manage the people in a workspace:
who exists (to assign work), add a colleague, deactivate one, change a role.
Reads take `users:view`; writes take `users:configure`.

| Call                   | What it does                                                                                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/users`        | Active users by default (`?status=all` or `inactive` to widen), newest first, cursor-paginated. Each row carries `id`, `full_name`, `email`, `status`, `roles[]`. |
| `GET /v1/users/{id}`   | One user. A foreign id is a 404.                                                                                                                                  |
| `POST /v1/users`       | Create a user (below).                                                                                                                                            |
| `PATCH /v1/users/{id}` | `full_name`, `status` (`active` / `inactive`), `role` or `role_id`, `branch_id`.                                                                                  |

## Creating a user

```json theme={null}
POST /v1/users
{ "email": "ada@acme.com", "full_name": "Ada Lovelace", "role": "Agent",
  "password": "an-initial-password", "send_welcome": false }
```

* **`role`** (name) or **`role_id`** — resolved server-side; `Super_Admin` can never
  be granted through the API.
* **`password`** optional. Given → the seat is login-ready immediately (no forced
  reset). Omitted → a temporary password is generated; it is returned **once** as
  `temp_password` in the response so you can hand it over, and the user must
  change it at first login.
* **`send_welcome`** — the welcome email (with the temporary password when one was
  generated) is sent **only** when this is `true`. Default off: an integration
  that provisions users usually has its own onboarding message.
* Honours `Idempotency-Key`.

Response: `201` with `user` (the row as `GET /v1/users/{id}` returns it),
`temp_password` (only when generated) and `welcome_email_sent`.

Errors: `409 ALREADY_EXISTS` (email already registered), `409 SEAT_LIMIT_REACHED`
(the workspace is at its seat allowance — `details.hint` says how many seats to
buy via `POST /v1/subscription/seats`; see [billing.md](/api-reference/billing#seats)),
`400 VALIDATION_ERROR` with `details.fields`.

## Deactivating and reactivating

`PATCH /v1/users/{id} { "status": "inactive" }` frees the seat; the user can no
longer sign in. Reactivating (`"active"`) goes through the same seat check as a
create and can answer `SEAT_LIMIT_REACHED`.

Two guards you cannot turn off: the API never deactivates the **last active
Company\_Admin** of a workspace (`409 CONFLICT`, `details.reason: last_admin`),
and never assigns `Super_Admin`.

Every change writes an `auditlog` row (`api_update`) naming the API key that acted.

## Parity with the AI assistant

`GET /v1/users` returns the same `id` / `full_name` / `email` the MCP `list_users`
tool returns, so an owner id resolved by either can be used by the other.