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

# Roles & Permissions

> Four hierarchical roles — viewer, editor, admin, platform — that control what users can do.

Tell uses a simple role-based access control (RBAC) system. Every user has a role in each workspace they belong to. Roles are hierarchical — higher roles inherit all permissions from lower ones.

## Roles

| Role         | What they can do                                                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Viewer**   | View analytics, dashboards, and shared content                                                                          |
| **Editor**   | Everything a Viewer can, plus create and edit their own boards, saved metrics, and queries                              |
| **Admin**    | Everything an Editor can, plus manage workspace members, settings, invite users, run raw SQL, and edit anyone's content |
| **Platform** | Everything an Admin can, plus cross-workspace operations (for self-hosted and enterprise deployments)                   |

## Permissions

Roles map to four explicit permissions. View is implicit for all workspace members.

| Permission  | Minimum role | What it controls                                       |
| ----------- | ------------ | ------------------------------------------------------ |
| `create`    | Editor       | Create/edit/share own content (boards, saved metrics)  |
| `raw_query` | Admin        | Execute raw SQL queries against the analytics database |
| `admin`     | Admin        | Manage workspace (members, settings, integrations)     |
| `platform`  | Platform     | Cross-workspace operations                             |

## Common scenarios

**Your analyst needs to build dashboards.** Give them the Editor role. They can create boards and saved metrics, but can't manage team members or run arbitrary SQL.

**A developer needs raw SQL access.** They need the Admin role. Editors can use built-in metrics and boards, but raw SQL requires Admin.

**Your DevOps team manages the Tell deployment.** Give them the Platform role on self-hosted installations. This allows cross-workspace operations like managing all workspaces and global settings.

## Assigning roles

Roles are assigned when inviting users to a workspace:

```bash theme={null}
# Invite as viewer (default)
curl -X POST https://your-tell-server/api/v1/admin/workspace/invites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "analyst@example.com", "workspace_id": "ws-1", "role": "editor"}'
```

Invitations expire after 7 days. The invited user must log in and accept the invite. Their email must match the invite.

## Workspace-scoped roles

A user can have different roles in different workspaces. For example, you might be an Admin in your team's workspace but a Viewer in a shared analytics workspace.

The role in the JWT token reflects the user's global role. Workspace-specific roles are checked separately when accessing workspace resources.

## The first user

The first user created during [setup](/api/authentication) automatically gets the Platform role — the highest privilege level. This user can then invite others and assign appropriate roles.