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

# Users and roles

> Manage users, role assignments, and role definitions.

Qustody RBAC is built on **users**, **roles**, and **role assignments**. See [User roles](/qustody/user-roles) for the conceptual model and the default 5-role / 12-resource / 6-action matrix.

## Users

### Create user

```http theme={null}
POST /v1/users
```

```bash theme={null}
curl -X POST https://api.qustody.io/v1/users \
  -H "Authorization: Bearer $QUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "Alice Doe",
    "external_id": "okta:00u..."
  }'
```

**Response 201**

```json theme={null}
{
  "id": "usr_01HXYZ...",
  "email": "alice@example.com",
  "name": "Alice Doe",
  "status": "active",
  "created_at": "2026-04-27T10:15:00Z"
}
```

### List users

```http theme={null}
GET /v1/users?status=active&page=1&per_page=50
```

### Get user

```http theme={null}
GET /v1/users/{id}
```

### Update user

```http theme={null}
PUT /v1/users/{id}
```

Updatable fields: `name`, `status` (`active`, `suspended`).

## Role assignments

### Assign role to user

```http theme={null}
POST /v1/users/{id}/roles
```

```bash theme={null}
curl -X POST https://api.qustody.io/v1/users/usr_01HXYZ/roles \
  -H "Authorization: Bearer $QUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "role_approver"}'
```

### Revoke role from user

```http theme={null}
DELETE /v1/users/{id}/roles/{roleId}
```

## Roles

Roles are read-only via the API in the current release. The five system roles are seeded automatically.

### List roles

```http theme={null}
GET /v1/roles
```

```json theme={null}
{
  "roles": [
    {"id": "role_admin", "name": "admin", "description": "Full access"},
    {"id": "role_operator", "name": "operator", "description": "Submit and manage transactions"},
    {"id": "role_viewer", "name": "viewer", "description": "Read-only access"},
    {"id": "role_approver", "name": "approver", "description": "Approve/reject transactions"},
    {"id": "role_compliance_officer", "name": "compliance_officer", "description": "Compliance and audit"}
  ]
}
```

### Get role

```http theme={null}
GET /v1/roles/{id}
```

Returns the role's full permission matrix as `(resource, action)` pairs.

## Required permissions

| Endpoint                               | Permission                    |
| -------------------------------------- | ----------------------------- |
| `POST /v1/users`                       | `users:create`                |
| `GET /v1/users*`                       | `users:read`                  |
| `PUT /v1/users/{id}`                   | `users:update`                |
| `POST /v1/users/{id}/roles`            | `users:update` + `roles:read` |
| `DELETE /v1/users/{id}/roles/{roleId}` | `users:update`                |
| `GET /v1/roles*`                       | `roles:read`                  |