Permission & Roles

Each Custom API definition declares which roles are allowed to call it.

Defining Permission

permission:
  [ power, admin ]

List one or more role names. At runtime, Minimal checks X-User-Roles against this list using OR logic — the user needs any one matching role.

How It Works at Runtime

Request arrives with:
  X-User-Roles: editor,admin

Definition requires:
  permission: [ power, admin ]

Check: is any role in X-User-Roles present in permission?
  editor ∈ [ power, admin ] → No
  admin  ∈ [ power, admin ] → Yes ✅

Result: Allowed

If no role matches, Minimal returns 403 Forbidden.

Role Names

Role names are free-form strings — they are whatever your system defines and passes in X-User-Roles. Two names have reserved meaning:

Role	Reserved meaning
power	Always has access to definition management APIs
admin	Always has access to definition management APIs

Definition management APIs (create, update, delete a definition) always require power or admin regardless of what is set in permission.

Multiple Roles

A user with multiple roles in X-User-Roles only needs one to match:

X-User-Roles: viewer,editor,power

permission: [ admin ]   → ❌ Forbidden — none match
permission: [ power ]   → ✅ Allowed — power matches
permission: [ viewer ]  → ✅ Allowed — viewer matches