# Authorization (RBAC)

Authorization lets your app ask "may this member do this?" without building a permissions system. It builds on [user management](/user-management/) memberships.

## Model

- **Permissions** are slugs you define, such as `reports:read` (lowercase letters, digits and `_.:-`, up to 128 characters). They match exactly; there are no wildcards.
- **Roles** bundle permissions. An environment role applies in every organization. A custom organization role exists only in its organization and replaces an environment role with the same slug there. Each role has a `priority` from 0 to 10000; higher wins.
- **Role assignments** add roles to a membership, organization-wide or on one resource (`resource: {type, id}`). An assignment on a resource grants that role's permissions on that resource only.

A role from another organization never applies, whatever refers to it, and inactive memberships hold no permissions.

## Checks

- `POST /v1/authorization/check` checks one permission for a membership (or a user and organization), optionally on a resource.
- `POST /v1/authorization/check/bulk` checks up to 100 at once.
- `GET /v1/organizations/{org}/memberships/{membership}/permissions` lists a membership's roles and permissions.

An unknown subject is denied, not an error. Checks are served from memory and validated against a per-environment version counter, so a role or membership change applies to the next check in every server, within 30 seconds at worst if the counter cannot be written.

## In tokens

End-user tokens issued in an organization carry `roles` (in priority order), `role` (the highest-priority organization-wide role) and `permissions` (sorted, at most 100). When there are more, the list is cut and `permissions_truncated: true` is set; a cut list only ever denies more. For decisions that must be exact, call the check API.

## Management API

`/v1/authorization/permissions…` and `/v1/authorization/roles…` need `authorization:read` or `authorization:write`; role assignments live under `/v1/organizations/{org}/memberships/{membership}/role_assignments`. Events: `permission.*`, `role.*` and `role_assignment.*`. The CLI has `ohauthcat roles` and `ohauthcat permissions`; Terraform has `ohauthcat_authorization_role` and `ohauthcat_authorization_permission`.

Plan limits for roles and permissions are not final; the pricing page is the source for them.
