YaqeenDocs
Back to Yaqeen

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 groupReviewerAdminMerchant
Holds: list, detail, explain (holds/, holds/{id}/explain/)ReadReadRead own, approved or released only
Hold case graph and orders (holds/{id}/case/, holds/{id}/orders/)ReadReadNo
Hold decisions (holds/{id}/decision/, holds/bulk-decision/)ChangeChangeNo
Appeals on a hold (holds/{id}/appeals/)Read, fileRead, fileRead own, file own
Appeal decisions (holds/appeals/{id}/decision/)ChangeChangeNo
Appeal documents (holds/appeals/{id}/documents/)ReadReadRead own, upload own
Cases and notes (cases/, cases/{id}/notes/)Read, add notesRead, add notesNo
Assign a case (cases/{id}/assign/)ChangeChangeNo
Case conclusions (cases/{id}/outcome/)Read, recordRead, recordNo
Case export, label audit (cases/{id}/export/, ops/label-audit/)YesYesNo
Review queue (queue/, queue/next/, queue/{id}/release/)YesYesNo
Workload, KPIs, weekly report (queue/workload/, ops/kpis/, ops/weekly-report/)ReadReadNo
Second-person approvals (approvals/)Read, decide, cancelRead, decide, cancelNo
Stores and payouts (stores/, payouts/)ReadReadRead own
Owners (owners/)ReadReadNo
New-store applications (intake/)Read, submit, mark papers, decideRead, submit, mark papers, decideNo
Suppressions (suppressions/)Read, add, endRead, add, endNo
Rules (rules/)Read, save, disable, backtestRead, save, disable, backtestNo
Reserves and disputes (reserves/, reserves/disputes/)Read, set, close, open and decide disputesRead, set, close, open and decide disputesOwn reserves and disputes, answer own disputes
Store risk (risk/)Read, record reviewRead, record reviewNo
Policy, approval limits, queue limits (policy/, approvals/settings/, queue/settings/)ReadRead, changeNo
Policy proposals (policy/proposals/)Read, propose, backtest, run in shadowAll of that, plus promote and roll backNo
Releases (ops/releases/)ReadReadNo
Monitoring and simulator (ops/monitoring/, ops/simulator/run/)YesYesNo
Audit log (audit/, audit/export/)ReadReadNo
Privacy requests and legal holds (privacy/)Read, log, close, place a legal holdSame, plus end a legal holdNo
Operations (ops/health/, ops/policy-history/, ops/audit-verify/, jobs/)NoYesNo
Recorded errors (ops/errors/): only the team that runs Yaqeen, since errors come from every customerNoNoNo
Data loading and scoring (ingest/, scoring/runs/)NoYesNo
Keys, usage, plan, webhooks, sandbox (keys/, usage/, webhooks/, sandbox/)NoYesNo
People (users/, users/invites/, users/{id}/reset-link/, users/merchants/, scim/v2/)NoYesNo
Hold messages (portal/holds/{id}/messages/)Read, writeRead, writeRead own, write own
Merchant portal (portal/, notifications/, devices/, reserves/mine/, reserves/disputes/mine/)NoNoYes
Assistant (assistant/chat/, assistant/act/)YesYesYes
Assistant usage (assistant/usage/)NoYesNo
MCP for Claude and Codex (mcp/)Yes, read-only toolsYes, read-only toolsNo
MCP policy (mcp/settings/)NoRead, change (signed-in session only, not a key)No
Search, onboarding checklist, saved views (search/, onboarding/, views/)YesYesNo

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#

CallWho 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.

ScopeRole
readReviewer, GET, HEAD and OPTIONS only
decideReviewer
ingestAdmin
scimAdmin
mcpReviewer, 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.

Up Down to moveEnter to openEsc to close