Users & Roles

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:

{
  "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.

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

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

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).

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.

Getting Started

Platform Concepts

App Guides — Office

App Guides — Access

App Guides — Sales

App Guides — Careers

App Guides — Project

App Guides — Guard

Integrations

Security & Compliance

Users

Roles

Service Accounts

Role Assignment via API

Permission Evaluation

​Users

​Roles

​Service Accounts

​Role Assignment via API

​Permission Evaluation

Users

Roles

Service Accounts

Role Assignment via API

Permission Evaluation