Roles and tokens

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.

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:

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:

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:

ce sites prompt example.com

See Add a site.

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.

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.

ce audit --limit 50