# Roles and tokens

> The three roles of people, the scopes of API tokens, install tokens, and who owns a token.

People have roles. Agents and scripts have API tokens. Roles and tokens use the same scopes, so Checkend checks people and agents the same way.

## Roles

Each person has one role for the whole organization. A role is not per site.

| Role | Scope | What the person can do |
|---|---|---|
| Admin | `admin` | Everything: tokens, webhooks, people, retention, limits and settings. |
| Member | `write:*` | Change sites, goals, annotations, findings and search connections. Not tokens of other people, webhooks, people or settings. |
| Viewer | `read:*` | Read only. |

- Only Admins and Members see the people list. A Viewer sees no email addresses of other people.
- The last admin stays. Checkend refuses to remove the last admin or to change the role of the last admin. Make another person admin first.
- Roles, viewer accounts and passkeys are free.

To invite people and change roles, see [People and invites](/docs/guides/people-and-invites.md).

## Token scopes

| Scope | Access |
|---|---|
| `read:*` | Read all projects. |
| `write:*` | Read and write all projects. |
| `read:<project>` | Read one project. |
| `write:<project>` | Read and write one project. |
| `admin` | Everything. |

Write includes read. Give agents read-only tokens, unless they must write.

Make a token:

```sh
ce tokens create --name "weekly agent" --scope 'read:*'
```

Checkend shows the secret one time. It stores only a hash of the token. List and revoke tokens:

```sh
ce tokens list
ce tokens revoke <id>
```

You can also manage tokens in **Settings → API tokens**.

## A token belongs to a person

Each token belongs to the person who made it. This is also true for an agent token that an admin makes, and for the token of an MCP app that a person approved.

- A token gets only scopes inside the role of its person.
- An admin sees and revokes all tokens.
- A Member or a Viewer sees, makes and revokes only their own tokens.
- When a person leaves, Checkend revokes all their tokens.

### A role change revokes tokens

When an admin gives a person a lower role, Checkend revokes each token of the person that is outside the new role. Checkend does not narrow the tokens. The agent gets a clear "not authenticated" error, not a mix of allowed and refused calls.

The role change takes effect on the next request of the person.

## Install tokens

An install token is a special token for one site. It starts with `ce_inst_` and has the scope `install:<site>`. It expires after 24 hours.

It can do only two things:

- check the install of its site,
- send one test event to its site.

It cannot read analytics, list sites, write data or sign in. The token API cannot make an install token. Only the install prompt makes one:

```sh
ce sites prompt example.com
```

See [Add a site](/docs/start/add-a-site.md).

## OAuth tokens for MCP apps

An MCP app that you approve on the consent page gets an access token for one hour and a refresh token.

- The access token belongs to you. It shows in your token list with the app name and "(MCP)".
- It works only at `/mcp`. The REST API refuses it.
- Each refresh gives a new access token and a new refresh token. The old ones stop.
- To end the access, revoke the token in **Settings** or with `ce tokens revoke`.

See [Connect your agent](/docs/start/connect-your-agent.md).

## Errors for missing access

| Case | HTTP status | `ce` exit code |
|---|---|---|
| No token, or a token that is not valid | 401 | 2 |
| A valid token without the scope or role for the action | 403 | 5 |

## The audit log

Each write by a token goes to the audit log: the token, its scopes, the interface (`rest`, `mcp`, `cli`, `ui` or `job`), the action, the target and the time. An admin reads it with `ce audit`, or in **Settings**.

```sh
ce audit --limit 50
```