# Roles

> viewer, content_viewer, handler, client_admin: what each may do.

Every person and key in a tenant has one role. Roles are cumulative: each one can do everything the one before it can.

## The roles

| Role             | Adds                                                                                                                                                            | Who holds it                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `viewer`         | Every operational read: agents, runs, usage, cost, evidence, knowledge-base health, limits and reports                                                          | People, machine keys, Atlantic staff                                           |
| `content_viewer` | Your content, read in place from your deployment (`/api/v1/content/...`, the `knowledge` tool)                                                                  | People, machine keys, and Atlantic staff only where your access rules allow it |
| `handler`        | Handler commands: pause and resume, caps, pre-approvals, approval decisions, releases, within your command settings and your deployment’s policy                | People only                                                                    |
| `client_admin`   | Access rules, API keys, the access review, the audit log, command settings, connectors, branding, where agents run, models, and the library’s Add to deployment | People only                                                                    |

Beside the ladder, **`billing`** lets a person run the tenant’s payments (payment methods, top-ups, auto-recharge, invoices, billing details and the purchase order number) while reading as a `viewer`. A person matched by a billing grant and another grant keeps the higher role and gains billing.

## Rules LightHouse fixes

- A machine key is `viewer` or `content_viewer`, never more.
- Commands, approvals, payments and changes to limits or access are made by a person signed in with a second factor, never by a key.
- Atlantic staff hold `viewer` on every tenant, and at most `content_viewer` where your rules say so. They never administer a tenant, and your access rules cannot give them more (`422 guard_rail`). See [Who can see what](/data-sovereignty/access/).
- A tenant always keeps at least one `client_admin`, so it cannot lock itself out.

## Setting roles

**Settings → Users and roles** (`client_admin`): grant a role by identity provider, group, email domain, email address or GitHub team. By API: `GET` and `PUT /api/v1/access`; a `PUT` with a stale version is refused with `409 version_conflict`. `GET /api/v1/access/review` is the access review, also as CSV. See the [Access and keys reference](/api/reference/access-and-keys/).

## What a refusal says

A route that needs a higher role answers `403 role_required`, naming the role. The [generated reference](/api/reference/) states each MCP tool’s role; see [MCP tools](/mcp/tools/).

Source: https://docs.atlanticagenticlabs.com/api/roles/