Event & system control — the platform tier

The most sensitive tier

Most Library scopes act on one business object. A few act on the organization’s trust material — the keys that sign its tokens, the secret that signs its webhooks, the domains and identity providers it accepts sign-ins from — or on the organization itself. Whoever holds these can change what every other check relies on.

They are ordinary entries in the Action Library: same grammar, same ceiling, same approval flow. What sets them apart:

• Always enforced. Every route below checks its scope on each call. A caller without it gets 403 with errorCode: "PERMISSION_DENIED" and the missing scope in required.
• Held implicitly only by Owners and Admins. Everyone else needs the scope explicitly, through a role or an approved request.
• Highest derived risk. Scopes ending in delete, revoke, suspend, issue, rotate_signing_key or regenerate_webhook_secret start at RiskLevel 3.

Keys and secrets

Scope	What it allows	Route
org.api_key.issue	create an organization API key	POST /api/org/{slug}/settings/keys/api-keys
org.api_key.issue	run the self-test for a key	POST /api/org/{slug}/settings/keys/api-keys/{keyId}/self-test
org.api_key.revoke	revoke an API key	DELETE /api/org/{slug}/settings/keys/api-keys/{keyId}
org.api_key.issue	create a plugin token	POST /api/org/{slug}/settings/keys/plugin-tokens
org.api_key.revoke	revoke a plugin token	DELETE /api/org/{slug}/settings/keys/plugin-tokens/{tokenId}
org.setting.rotate_signing_key	rotate the organization’s signing key	POST /api/org/{slug}/settings/keys/signing-key/rotate
org.setting.regenerate_webhook_secret	regenerate the webhook signing secret	POST /api/org/{slug}/settings/keys/webhook-secret/regenerate

Domains, sign-in and structure

Scope	What it allows	Route
org.org.verify_domain	verify a domain for the organization	POST /api/org/{slug}/settings/domains/verify · POST /api/org/{slug}/settings/domains/auto-configure
org.idp_connection.update	add, test or remove an identity-provider connection	POST /api/org/{slug}/settings/federation · POST /api/org/{slug}/settings/federation/{providerId}/test · DELETE /api/org/{slug}/settings/federation/{providerId}
org.setting.update	change organization settings: general, security policy, member policies, domains, SCIM tokens	PUT /api/org/{slug}/settings/general · PUT /api/org/{slug}/settings/security · PUT /api/org/{slug}/settings/member-policies · PUT /api/org/{slug}/settings/domains · POST /api/org/{slug}/settings/scim/tokens
org.org.create	create a sub-organization	POST /api/org/{slug}/sub-orgs
org.org.delete	delete a sub-organization	DELETE /api/org/{slug}/sub-orgs/{subSlug}

Ownership transfer is not a scope

Handing the organization to another person is reserved to the Owner and cannot be granted, delegated or approved by anyone else. POST /api/org/{slug}/transfer-ownership sends a proposal, confirmed with the Owner’s passkey; nothing changes until the recipient accepts it with their own passkey. The Owner can withdraw the proposal with POST /api/org/{slug}/transfer-ownership/cancel before it is accepted. Sending a proposal requires the Ownership Transfer add-on; without it the call returns 402 with error: "ADDON_REQUIRED".

RiskLevel → approval routing (whole Library)

Every form that grants scopes carries a RiskLevel from 0 to 4. It is the bridge between the catalog and the approval line.

Where the level comes from. Each scope has a floor that follows from its last segment:

Last segment of the scope	Floor
read · list	1
delete · revoke · suspend · issue · rotate_signing_key · regenerate_webhook_secret	3
anything else — every other action, a page scope (view.members), a custom scope (shipment.approve)	2

A form takes the highest floor among the scopes it grants. Its author can raise the level, up to 4, and can never set it below the floor.

What the level does.

Risk	Name	Who approves
0	Routine	no approver
1	Standard	no approver
2	Elevated	the nearest person above the requester who holds the requested scope
3	Critical	the nearest person above the requester who holds the scope and is a board member or the Owner
4	Sovereign	the Owner

How the line is found:

• Above the requester means the reporting line, walked upward from the requester, nearest first.
• Holds the scope is the ceiling: the approver’s own grant must cover the request, including its constraints. It is checked when the line is built and again at the moment of approval.
• Owner-only scopes are stricter. A request for a billing scope (view.billing, org.org.billing_manage) or a Roost scope (view.roost, org.roost_…, org.setting.roost_…) — or for a wildcard that would include one, such as org.* or view.* — can be approved only by the Owner, or by someone who holds that scope explicitly. An Admin’s organization-wide access does not count.
• Line mode decides how many of the qualifying people must approve: single takes the nearest one, chain and parallel take all of them, quorum takes the configured number.
• If nobody above the requester both holds the scope and is senior enough, a request for access stays submitted until an approver is designated — it is not sent to someone who could not approve it. A request that grants nothing (a plain document approval) goes to the most senior person above the requester who meets the level; if nobody meets the level, it stays submitted.
• A form that defines its own approval line uses the people in that line instead of the reporting line.
• Levels 0–1 complete without an approver only when the requester is the Owner, the account owner or the organization’s representative, and the grant passes the same checks as an approval (an Owner-only scope only for the Owner). Otherwise the request stays submitted.
• Requests raised by an agent are never completed without a human approver, whatever the level.

Every approval and rejection is confirmed with the approver’s passkey at the moment it is given.

---

Related: Action Library · Custom actions · Protected boundary · Capability grants · Events