Authorization

YorAuth provides a full Role-Based Access Control (RBAC) system for your application users, with optional Attribute-Based Access Control (ABAC) policy layers for fine-grained conditional logic.

How It Works

The authorization system is built around three core concepts:

• Roles — Named collections of permissions (e.g., admin, editor, viewer)
• Permissions — Specific abilities in resource:action format (e.g., posts:create, users:delete)
• Users — Your application's end-users, identified by an external user_id string

Roles are assigned to users. Permissions are assigned to roles. When you check whether a user can perform an action, YorAuth evaluates all roles the user holds and returns a boolean result — with Redis-cached results for sub-10ms repeat checks.

User → Roles → Permissions → Authorization Check

Teams are also supported: roles can be assigned to teams, and team members inherit those roles automatically.

RBAC Flow

POST /api/v1/applications/{applicationId}/authz/check

1. Load user's permission set (Redis cache, 1hr TTL)
2. Match the requested permission against the set (wildcard-aware)
3. If ABAC params provided, evaluate active ABAC policies (AND logic)
4. Return { allowed: true|false }

Cache invalidation is O(1) — any role or permission change increments a version key that makes all stale cache entries immediately ignored.

API Authentication

All authorization API calls require a valid JWT Bearer token. The token must have the appropriate scope claim for the operation being performed:

Authorization: Bearer <jwt>

Sections

• Roles — Create, update, delete roles and assign them to users
• Permissions — Permission format, CRUD, and authorization check endpoints
• Wildcard Matching — How posts:*, *:read, and *:* patterns work
• Policies — ABAC policies for attribute-based conditional authorization
• Teams — Group users into teams and assign roles at the team level

Quick Example

# 1. Create a role
curl -X POST https://api.yorauth.com/api/v1/applications/your-application-id/roles \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "display_name": "Editor",
    "permissions": ["posts:create", "posts:update", "posts:delete"]
  }'

# 2. Assign the role to a user
curl -X POST https://api.yorauth.com/api/v1/applications/your-application-id/users/user-123/roles \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "<role-uuid>"}'

# 3. Check the permission
curl -X POST https://api.yorauth.com/api/v1/applications/your-application-id/authz/check \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-123", "permission": "posts:create"}'

Response:

{
  "allowed": true,
  "permission": "posts:create",
  "cached": false
}

Scoped Roles

Roles can be assigned with an optional scope to support multi-tenant applications. A user can hold different roles in different organizational contexts:

{ "role_id": "<uuid>", "scope": "org:acme-corp" }

When checking a permission with a scope, both global roles (no scope) and scoped roles matching that scope are evaluated:

{ "user_id": "user-123", "permission": "reports:export", "scope": "org:acme-corp" }