# Roles & Permissions

Workspace roles with their scopes and data scope, and the effective permissions a member resolves to.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### POST /roles/:role_id/users

Assign a workspace member to a role. You cannot assign a role that grants scopes you do not hold (unless you have admin). The member's prior role is remembered so removal can restore it.

**Scopes:** `permissions:write` — [full detail](./roles/post-roles-role-id-users.md)

### POST /roles

Create a custom role. You can only grant scopes you hold yourself (unless you have the admin scope). Scopes are strings like "contacts:write".

**Scopes:** `permissions:write` — [full detail](./roles/post-roles.md)

### DELETE /roles/:role_id

Delete a custom role. Fails if any users are still assigned (unassign them first). Preset roles cannot be deleted.

**Scopes:** `permissions:write` — [full detail](./roles/delete-roles-role-id.md)

### GET /roles/effective

Resolve a workspace member's live effective permissions (is_admin, scopes, data_scope) via the same engine RLS uses. Pass ?user_id=<uuid>; omit to resolve the calling key's creator. Use this to verify what a user can actually do.

**Scopes:** `permissions:read` — [full detail](./roles/get-roles-effective.md)

### GET /roles/:role_id

Fetch a single role by UUID with its resolved scopes, visibility, and assigned-user count.

**Scopes:** `permissions:read` — [full detail](./roles/get-roles-role-id.md)

### GET /roles/:role_id/users

List the workspace members currently assigned to a role.

**Scopes:** `permissions:read` — [full detail](./roles/get-roles-role-id-users.md)

### GET /roles

List all roles in this workspace (preset and custom) with their resolved scopes, data scope, visibility, and assigned-user counts.

**Scopes:** `permissions:read` — [full detail](./roles/get-roles.md)

### DELETE /roles/:role_id/users/:user_id

Remove a workspace member from a role, restoring their previous role (or viewer if none).

**Scopes:** `permissions:write` — [full detail](./roles/delete-roles-role-id-users-user-id.md)

### PATCH /roles/:role_id

Update a custom role (name, description, scopes, data_scope, visibility). Preset roles cannot be edited. You can only set scopes you hold yourself unless you have the admin scope. Renaming keeps existing assignments intact.

**Scopes:** `permissions:write` — [full detail](./roles/patch-roles-role-id.md)