Authorization API

Authorization answers the question "what can this user do?". Authentication (covered by the OAuth API) confirms who the user is and issues an access token — typically a JWT (RFC 7519, a signed JSON payload the client presents on each request). Authorization then decides whether that authenticated caller may perform a specific action on a specific resource.

LumoAuth supports three authorization models that address different problems. You can use one, or layer them.

Base URL

All API endpoints are relative to your organization's base URL: https://app.lumoauth.dev/orgs/{orgId}/api/v1/

Authorization Models

1. RBAC (Role-Based Access Control)

Users are assigned roles, and each role carries a set of named permissions. A check asks: "does this user have permission X?" — a yes/no lookup against the user's role set.

User "john" → Role "Editor" → Permissions ["document.edit", "document.view"]

Question: Can John edit documents?
Answer: Yes, because John has the Editor role, which includes document.edit

Use RBAC when access is driven by job function and the permission set is small enough to enumerate. It is the simplest model and usually the right starting point.

2. ABAC (Attribute-Based Access Control)

A policy engine evaluates attributes of the subject (user), resource, action, and environment (time, IP, device). Attributes are dynamic — they change per request — so ABAC can express rules RBAC cannot.

Rule: Users can edit documents they own

Context:
  - user.id: 123
  - document.owner_id: 123
  - user.department: "engineering"

Question: Can user 123 edit this document?
Answer: Yes, because user.id == document.owner_id

Use ABAC when access depends on context: resource ownership, classification, time-of-day, location, or device posture.

3. ReBAC / Zanzibar (Relationship-Based Access Control)

Introduced in Google's Zanzibar paper (2019), this model stores access as relation tuples of the form object#relation@subject, for example document:readme#editor@user:alice ("alice is an editor of document readme"). A check walks the relation graph, following inheritance and userset rewrites (for example "owners are also editors", "team members inherit the team's access").

Relationships:
  - document:readme#owner@user:alice
  - folder:projects#viewer@team:engineering#member
  - document:readme#parent@folder:projects

Question: Can Bob (engineering team member) view the readme?
Answer: Yes, because:
  1. Bob is a member of team:engineering
  2. team:engineering viewers can view folder:projects
  3. document:readme is in folder:projects
  4. Therefore, Bob can view document:readme

Use Zanzibar when access is driven by hierarchy and relationships: folders containing files, teams owning projects, organizations containing workspaces.

Understanding Zanzibar

Zanzibar stores relationships between things. A relationship is a single statement written as an object, a relation, and a subject.

Anatomy of a Relationship

Part	Example	Meaning
object	document:readme	The resource being protected (type:id)
relation	editor	The type of access or relationship
subject	user:alice	Who has this relationship (type:id)

Subjects can also be usersets — for example team:engineering#member refers to every user with a member relation on team:engineering, and can be used anywhere a user could.

Example: Google Drive-style sharing

# Alice owns a folder
folder:shared#owner@user:alice

# Bob can view the folder (Alice shared it)
folder:shared#viewer@user:bob

# A document is inside the folder
document:report#parent@folder:shared

# Relation rules (schema):
# - Viewers of a folder can view documents in that folder
# - Editors of a folder can edit documents in that folder
# - The owner is also an editor

Question: Can Bob view the report?

1. Bob is a viewer of folder:shared
2. document:report has parent = folder:shared
3. By the schema rules, folder viewers can view contained documents
4. Therefore, Bob can view the report ✓

Why Zanzibar?

Benefit	Description
Inheritance	Permissions flow through hierarchies (folders → files) without copying rules
Scale	The model handles large relation graphs efficiently
Flexibility	Models sharing, teams, organizations, and workflows with one primitive
Auditability	Answers "why can this user access this?" by showing the traversal

Available Endpoints

Method	Path	Purpose
POST	/api/v1/authz/check	Check a single permission for the current user. Details
POST	/api/v1/authz/check-bulk	Check multiple permissions at once, returning individual results. Details
POST	/api/v1/authz/check-any	Pass if the user has at least one of the permissions (OR). Details
POST	/api/v1/authz/check-all	Pass only if the user has all of the permissions (AND). Details
POST	/api/v1/zanzibar/check	Relationship check: "is user X a viewer of document Y?". Details
GET	/api/v1/authz/permissions	List all permissions granted to the current user. Details

Choosing the Right Model

Use Case	Recommended Model
"Can this admin manage users?"	RBAC — check if the user has the admin role
"Can this user edit their own profile?"	ABAC — check user.id == profile.owner_id
"Can this user view this shared folder?"	Zanzibar — check the viewer relationship
"Can users in the Sales team access leads?"	Zanzibar — team membership gates resource access
"Can this user access during business hours?"	ABAC — include time context in the check

Next Steps

• Permission Checks — call the RBAC/ABAC check endpoints.
• Zanzibar Checks — relationship-based checks.
• ABAC Policies and Attributes — define the ABAC rules that check evaluates.