> ## 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 & Roles

> Understand how users, roles, and scopes work across the Essal platform.

Access control in Essal is unified across all six apps through a single role and permission system managed by **Essal Access**. Every API call is authenticated as a user or service account and evaluated against that principal's assigned roles.

## Users

A **User** represents a human identity within a workspace. Users are created in Access and can be granted roles in any combination of apps. A user's profile includes:

```json theme={null}
{
  "id": "usr_01HXYZ1234",
  "email": "jane.doe@example.com",
  "display_name": "Jane Doe",
  "status": "active",
  "roles": ["office:editor", "project:member", "sales:viewer"],
  "created_at": "2025-03-10T10:00:00Z",
  "last_seen_at": "2026-07-11T16:45:00Z"
}
```

## Roles

Roles follow a `app:level` naming convention. Each role grants a predefined set of permissions within that app.

| Role              | Access Level                                             |
| ----------------- | -------------------------------------------------------- |
| `office:viewer`   | Read-only access to documents and files                  |
| `office:editor`   | Create and edit documents; cannot delete                 |
| `office:admin`    | Full control including delete and permissions management |
| `sales:viewer`    | Read CRM records                                         |
| `sales:rep`       | Create and update contacts and deals                     |
| `sales:admin`     | Manage pipelines and configure CRM settings              |
| `project:viewer`  | View projects and tasks                                  |
| `project:member`  | Create tasks, log time, comment                          |
| `project:admin`   | Create projects, manage sprints, assign members          |
| `guard:auditor`   | Read-only access to audit logs and alerts                |
| `guard:admin`     | Manage policies, configure alert rules                   |
| `workspace:admin` | Super-admin; full access to all apps and settings        |

## Service Accounts

Server-to-server integrations should use **Service Accounts** rather than user credentials. A service account is a non-human identity with an API key and an explicit scope list.

```bash theme={null}
POST /v1/access/service-accounts
{
  "name": "crm-sync-bot",
  "scopes": ["sales:read", "sales:write"],
  "description": "Syncs deal data from the external CRM"
}
```

## Role Assignment via API

```bash theme={null}
PATCH /v1/access/users/usr_01HXYZ1234
{
  "roles": ["office:editor", "project:member", "sales:viewer"]
}
```

<Note>
  Role changes take effect immediately for new API requests. Existing active sessions are re-evaluated on their next token refresh (within 5 minutes for OAuth tokens).
</Note>

## Permission Evaluation

Guard evaluates permissions in order: explicit deny → role-based allow → default deny. This means a Guard policy can override a role's default permissions for specific resources or actions.