Skip to main content
A user token carries its owner’s workspace role, read live on every call. This page is what that role reaches.

​
The matrix

Roles are cut by how much they widen Peeve’s reach, not by seniority. Two details that catch people out:
Responder holds the kill switch. The safe direction must be available to whoever is on shift, not only to an owner who may be asleep.
Developer holds none of the gated capabilities. It is a reach-restricted, technical-setup role: the install, the snippet, the CLI, widget appearance, connectors, and viewing the dashboard — none of which are gated by this matrix. It widens Peeve’s reach the least of any role that can still do setup.A Developer can see the workspace publishable and secret keys, which an Admin cannot. That is a different axis — see Credentials.
Every role can read. That mirrors the dashboard, where every role can view the console.

​
Which role each endpoint needs

The API maps onto the capability the dashboard already requires for the same act, so the two cannot drift.
PATCH /v1/contacts/{id}/token sits on grant rather than something weaker because it is the same class of act as the contact page’s “issue access”: it puts a credential for one of your users into Peeve. A credential that may only read must not be able to do that.
The per-contact MCP endpoint needs reply when called with a user token — a teammate pointing their assistant at one customer is the same act as picking up that customer’s hand-off in the console, so it needs the same reach and no more. Viewer and Developer are refused outright.
POST /v1/users and POST /v1/answer take a secret key rather than a user token, so the role matrix does not apply to them.

​
When a role is insufficient

A 403 that names both the role you resolved to and the capability you lacked — the two facts needed to fix it.
The fix is not to mint a more powerful token. A user token carries its owner’s role; there is no way to issue yourself a wider one. The fix is either a role change in Settings → Team, or a token from a teammate who already holds the capability.

​
Unrecognised roles fail closed

Any stored role value that is not one of the five folds to Viewer, the least-privilege role, so a bad value can never widen reach. The legacy member value maps to responder, which is the reach it historically carried.

​
Every call is attributed

Each API and MCP call is logged with the token id — never the token — plus the user, the role that resolved, the action, the filters used and the result count. Configuration writes also record before and after. That is what lets a workspace answer “who changed this”, and it is why MCP requires a named credential rather than a shared one. Free-text and email lookups are recorded as <redacted>: they would otherwise carry your own customers’ personal data into the log.