Roles & Permissions Overview

The AuthSec RBAC system provides granular, scoped access control for multi-tenant applications. It supports role-based permissions with both tenant-wide and resource-scoped access.

Base URL

https://dev.api.authsec.dev/uflow

Key Concepts

Roles

Roles define a named set of permissions that can be assigned to users. Each role has a name, description, and a set of associated permissions.

Permissions

Atomic permission units defined as resource:action pairs (e.g., users:read, billing:write). Permissions are registered individually and then attached to roles.

Role Bindings

The association between a user and a role, optionally scoped to a specific resource. Bindings can be:

• Tenant-wide (scope = NULL): Permission applies across the entire tenant
• Resource-scoped (scope_type + scope_id): Permission limited to a specific resource

Scopes

Named access levels (e.g., read, write, admin) that map to resources. Scopes define what resources a user can access and are embedded in JWT tokens.

API Scopes (OAuth)

OAuth-style scope contracts that map to internal permissions. Used for client-facing API authorization.

RBAC Architecture

User → Role Binding → Role → Role Permissions → Permission (resource:action)
                  ↓
           Scope (tenant-wide or resource-scoped)

Admin vs End-User APIs

The RBAC system provides parallel APIs for two contexts:

Context	Base Path	Database	Use Case
Admin	/uflow/admin/*	Primary/Master DB	Global admin operations
End User	/uflow/user/rbac/*	Tenant DB	Tenant-scoped operations

Both contexts support the same CRUD operations for roles, permissions, bindings, and scopes.

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer YOUR_JWT_TOKEN

API Sections

Roles & Bindings

Create, list, update, and delete roles. Assign roles to users via role bindings.

Permissions

Register atomic permissions, list permissions with role counts, and manage resource-action pairs.

Scopes

Manage scope-to-resource mappings for fine-grained access control.

API Scopes (OAuth)

Create OAuth scope contracts that map to internal permissions.

Authorization (Policy Check)

Runtime policy checking for authorization decisions.