Skip to content
Dashboard
Theme
Theme

Authorization (RBAC)

Permissions, environment and organization roles, resource-scoped role assignments and permission checks for your end users.

View Markdown

Authorization lets your app ask “may this member do this?” without building a permissions system. It builds on user management memberships.

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

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

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.

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