#Roles & permissions

Ratifia controls who in your org can do what through roles. A role is a named bundle of permissions, and a person's access is the union of every role they're assigned. Roles and their assignments are owned by Ratifia, per org, so access doesn't drift from wherever your team happens to sign in.

#Permissions

A permission is a single coarse capability. The full vocabulary:

Permission	Grants
`decisions:read`	see decisions in the Inbox
`decisions:decide`	approve / reject decisions
`policies:read`	view approval policies
`policies:write`	create / edit approval policies
`approvers:write`	manage approvers
`settings:write`	change org settings
`members:manage`	manage members and their role assignments
`roles:manage`	create / edit / delete custom roles
`apikeys:manage`	manage API keys
`billing:read` / `billing:write`	view / manage billing
`usage:read`	view usage
`audit:read`	read the audit log

The same vocabulary is shared by the dashboard (what it shows you) and the API (what it lets you call), so a permission means the same thing wherever it's checked.

Roles govern people. An API key is scoped to its org, not to a role: it is not narrowed by the permissions above.

#Built-in roles

Two roles ship with every org and are always present. They're defined in code, not stored as editable rows, so they never drift:

admin. Full access, including managing roles, members, and billing.
approver. Review and decide (decisions:read, decisions:decide) with read-only visibility on policies and usage.

Built-in roles can't be edited or deleted, and their names (admin, approver) are reserved, so you can't create a custom role with either name.

#Custom roles

Need something between the two? Create a custom role with exactly the permissions you choose. Custom roles are org-scoped and managed in the dashboard under Roles (or via /v1/roles, gated on roles:manage). Deleting a custom role also drops it from everyone it was assigned to.

#Assigning roles

Assign roles to people in the dashboard under Members (or via /v1/members, gated on members:manage). Each member lists their roles; add or remove assignments there. A member with several roles gets the combined permissions of all of them.

Nobody is locked out by default

A person with no explicit role assigned still gets a safe default so they're never stranded: a solo account resolves to admin, and a team member with nothing assigned yet gets the approver baseline (they can review). Any explicit assignment, including a restrictive custom role, always overrides this default.

#The last-admin guard

An org can never lose its ability to administer itself:

Removing the final admin from an org is rejected. There must always be at least one admin.
The org owner's admin role is permanent; nobody, not even the owner, can remove it.

#Enforcement

Permissions are enforced server-side: a request from someone lacking the required permission is rejected with 403 insufficient_permission. The dashboard uses the same vocabulary to hide actions a person can't take, so the UI and the API agree on who can do what.