App permissions

App permissions are custom permissions you define for your own application. You register them in Userbox, assign them to users via roles or direct grants, and then check them from your application backend using a single API call.

Permission key format

Every app permission has a key with the format namespace.resource.action:

• namespace — the domain or product area (e.g., finance, health)
• resource — the data type or feature being controlled (e.g., payables, reports)
• action — the operation being permitted (e.g., approve, view, create)

Examples:

finance.payables.approve
finance.payables.create
finance.reports.view
health.reports.view
health.users.update

You choose the namespace, resource, and action. Userbox stores the key and enforces it — your backend decides what it means.

The workspace-scoped check model

Every permission check in Userbox includes a workspace ID. This means the same user can have different permissions in different workspaces.

Your app backend
  │
  ├─ POST /v1/access/check
  │    body: { user_id, workspace_id, permission }
  │
  └─ Userbox API
       │
       └─ { allowed: true | false }
             │
             └─ Your app enforces the result

Your application is responsible for retrieving the workspace ID from its own data model and including it in every check call. Userbox never infers the workspace from the request context.

Calling the access check API

POST /v1/access/check
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "user_id": "ub_user_abc123",
  "workspace_id": "ub_ws_xyz789",
  "permission": "finance.payables.approve"
}

Response:

{
  "allowed": true
}

If allowed is false, the user does not have the permission in the specified workspace. Your application is responsible for returning the appropriate error to the end user.

B2B SaaS examples

Finance platform

A finance platform defines permissions for its accounts payable and reporting modules:

Permission key	What it controls
finance.payables.create	Submit a new invoice or payment request
finance.payables.approve	Approve or reject an invoice
finance.reports.view	Access financial reports

An "Approver" role in the workspace carries finance.payables.approve. A "Viewer" role carries only finance.reports.view. When a user attempts to approve an invoice, the backend calls /v1/access/check with the relevant workspace and permission — the result determines whether the action proceeds.

Health platform

A health platform controls access to clinical data and patient management:

Permission key	What it controls
health.reports.view	Read health monitoring data and reports
health.users.update	Modify patient records

Why workspace-scoped?

A doctor at a hospital using two clinics should have access to patient data in the clinic where they practice, not the other. Without workspace scoping, you would need to model this isolation yourself. With workspace scoping, Userbox handles the boundary — your permission check just includes the workspace ID for the clinic the action is happening in.

What's next

• API reference — Full access check endpoint documentation