Reference
Roles and permissions
Which role can call which group of endpoints.
This page lists what each role can do in each group of endpoints. For what the roles mean, read Roles.
How to read the table#
- Read means GET requests. Change means POST, PUT, PATCH or DELETE.
- No means the call is refused with
403. - Own means the merchant sees only the data of its own owner. Other data returns
404. - Paths start with
/api/v1/.
Roles by endpoint group#
| Endpoint group | Reviewer | Admin | Merchant |
|---|---|---|---|
Holds: list, detail, explain (holds/, holds/{id}/explain/) | Read | Read | Read own, approved or released only |
Hold case graph and orders (holds/{id}/case/, holds/{id}/orders/) | Read | Read | No |
Hold decisions (holds/{id}/decision/, holds/bulk-decision/) | Change | Change | No |
Appeals on a hold (holds/{id}/appeals/) | Read, file | Read, file | Read own, file own |
Appeal decisions (holds/appeals/{id}/decision/) | Change | Change | No |
Appeal documents (holds/appeals/{id}/documents/) | Read | Read | Read own, upload own |
Cases and notes (cases/, cases/{id}/notes/) | Read, add notes | Read, add notes | No |
Assign a case (cases/{id}/assign/) | Change | Change | No |
Case conclusions (cases/{id}/outcome/) | Read, record | Read, record | No |
Case export, label audit (cases/{id}/export/, ops/label-audit/) | Yes | Yes | No |
Review queue (queue/, queue/next/, queue/{id}/release/) | Yes | Yes | No |
Workload, KPIs, weekly report (queue/workload/, ops/kpis/, ops/weekly-report/) | Read | Read | No |
Second-person approvals (approvals/) | Read, decide, cancel | Read, decide, cancel | No |
Stores and payouts (stores/, payouts/) | Read | Read | Read own |
Owners (owners/) | Read | Read | No |
New-store applications (intake/) | Read, submit, mark papers, decide | Read, submit, mark papers, decide | No |
Suppressions (suppressions/) | Read, add, end | Read, add, end | No |
Rules (rules/) | Read, save, disable, backtest | Read, save, disable, backtest | No |
Reserves and disputes (reserves/, reserves/disputes/) | Read, set, close, open and decide disputes | Read, set, close, open and decide disputes | Own reserves and disputes, answer own disputes |
Store risk (risk/) | Read, record review | Read, record review | No |
Policy, approval limits, queue limits (policy/, approvals/settings/, queue/settings/) | Read | Read, change | No |
Policy proposals (policy/proposals/) | Read, propose, backtest, run in shadow | All of that, plus promote and roll back | No |
Releases (ops/releases/) | Read | Read | No |
Monitoring and simulator (ops/monitoring/, ops/simulator/run/) | Yes | Yes | No |
Audit log (audit/, audit/export/) | Read | Read | No |
Privacy requests and legal holds (privacy/) | Read, log, close, place a legal hold | Same, plus end a legal hold | No |
Operations (ops/health/, ops/policy-history/, ops/audit-verify/, jobs/) | No | Yes | No |
Recorded errors (ops/errors/): only the team that runs Yaqeen, since errors come from every customer | No | No | No |
Data loading and scoring (ingest/, scoring/runs/) | No | Yes | No |
Keys, usage, plan, webhooks, sandbox (keys/, usage/, webhooks/, sandbox/) | No | Yes | No |
People (users/, users/invites/, users/{id}/reset-link/, users/merchants/, scim/v2/) | No | Yes | No |
Hold messages (portal/holds/{id}/messages/) | Read, write | Read, write | Read own, write own |
Merchant portal (portal/, notifications/, devices/, reserves/mine/, reserves/disputes/mine/) | No | No | Yes |
Assistant (assistant/chat/, assistant/act/) | Yes | Yes | Yes |
Assistant usage (assistant/usage/) | No | Yes | No |
MCP for Claude and Codex (mcp/) | Yes, read-only tools | Yes, read-only tools | No |
MCP policy (mcp/settings/) | No | Read, change (signed-in session only, not a key) | No |
Search, onboarding checklist, saved views (search/, onboarding/, views/) | Yes | Yes | No |
Some rows mix two kinds of check. The route allows several roles, and the service then checks the role for the change. For example, portal/holds/{id}/messages/ accepts merchants and staff, and the service then limits a merchant to the messages of its own holds.
Second-person approvals#
Reviewers and admins can approve most waiting changes. Changes to the policy and to accounts need an admin as the second person. The person who asked can never approve their own change. Only that person or an admin can cancel a waiting change. See Second-person approval.
Calls that need no role#
| Call | Who can use it |
|---|---|
auth/csrf/, auth/login/ | Anyone. Sign-in is limited. |
auth/invite/accept/ | Anyone with an invitation token. |
auth/password/reset/ | Anyone with a reset token. |
auth/me/, auth/logout/, auth/password/ | Any signed-in person. |
trust/status/, trust/controls/, trust/incidents/ (GET) | Anyone, with no sign-in. |
Writing incidents under trust/incidents/ | Platform operator accounts only. A customer admin cannot. |
Roles of an API key#
A key acts with a role. The role comes from the highest scope on the key.
| Scope | Role |
|---|---|
read | Reviewer, GET, HEAD and OPTIONS only |
decide | Reviewer |
ingest | Admin |
scim | Admin |
mcp | Reviewer, and only POST /mcp/ |
A key is also limited by its scopes, and it can never reach users, keys, webhooks, privacy, usage or sandbox. An OAuth token from Claude or Codex belongs to a person, acts with that person's role, and works at the MCP address only. See Authentication.
Related#
- Roles: what each role is for.
- Invite users and set roles: give someone a role.
- Authentication: how a key gets its role.
- Errors: the
403 forbiddenanswers and their fixes.