Roles & Permissions

Roles & Permissions

The admin system uses a role-based access control (RBAC) model with granular permissions. Roles are stored in the ADMIN_DB D1 database and cached at the edge via KV.

Built-in Roles

Three roles are seeded by the migration and cover the most common access patterns:

Role	Display Name	Description	Permissions
viewer	Viewer	Read-only access to admin dashboards and logs	6 permissions
editor	Editor	Read and write access to configuration, flags, and tiers	16 permissions
super-admin	Super Admin	Full administrative access including user management and role assignment	27 permissions (all)

Super-admin bypass: Users with the super-admin role skip all permission checks — similar to Unix root. This is enforced in the middleware before any permission evaluation occurs.

Viewer Permissions

admin:read, audit:read, metrics:read, config:read, users:read, flags:read

Editor Permissions

admin:read, audit:read, metrics:read, config:read, config:write,
users:read, flags:read, flags:write, tiers:read, tiers:write,
scopes:read, scopes:write, endpoints:read, endpoints:write,
announcements:read, announcements:write

Super-Admin Permissions

All 27 permissions (see full list below). Super-admins also bypass the permission check entirely.

All 27 Permissions

Defined in AdminPermissionSchema (worker/schemas.ts):

Permission	Category	Description
admin:read	Admin	View admin dashboard and system state
admin:write	Admin	Modify admin system configuration
audit:read	Audit	Query audit log entries
metrics:read	Metrics	View system metrics and analytics
config:read	Config	Read tier, scope, and endpoint configuration
config:write	Config	Modify tier, scope, and endpoint configuration
users:read	Users	View user list and user details
users:write	Users	Update user records
users:manage	Users	Suspend, activate, and manage user lifecycle
flags:read	Flags	View feature flags
flags:write	Flags	Create, update, and delete feature flags
tiers:read	Tiers	View tier configuration
tiers:write	Tiers	Create, update, and delete tier configuration
scopes:read	Scopes	View scope configuration
scopes:write	Scopes	Create, update, and delete scope configuration
endpoints:read	Endpoints	View endpoint auth overrides
endpoints:write	Endpoints	Create, update, and delete endpoint auth overrides
announcements:read	Announcements	View system announcements
announcements:write	Announcements	Create, update, and delete announcements
roles:read	Roles	View role definitions
roles:write	Roles	Create and modify role definitions
roles:assign	Roles	Assign and revoke roles for users
keys:read	API Keys	View API key metadata
keys:write	API Keys	Create API keys
keys:revoke	API Keys	Revoke API keys
storage:read	Storage	View storage statistics and data
storage:write	Storage	Clear cache, run vacuum, and manage storage

Role Resolution Flow

Every admin API request resolves the caller’s role and permissions before evaluating access. The flow prioritizes speed via KV caching:

flowchart TD
    A["Incoming Request<br/>with Clerk JWT"] --> B{"JWT valid?<br/>verifyClerkJWT()"}
    B -->|No| C["401 Unauthorized"]
    B -->|Yes| D{"publicMetadata.role<br/>=== 'admin'?"}
    D -->|No| E["403 Forbidden<br/>(not an admin)"]
    D -->|Yes| F{"KV cache hit?<br/>admin:role:{userId}"}
    F -->|Hit| G["Use cached<br/>role + permissions"]
    F -->|Miss| H["D1 query<br/>JOIN admin_role_assignments<br/>→ admin_roles"]
    H --> I{"Assignment found<br/>and not expired?"}
    I -->|No| J["403 Forbidden<br/>(no active role)"]
    I -->|Yes| K["Write-through<br/>to KV cache<br/>TTL 300s"]
    K --> G
    G --> L{"Has required<br/>permission?"}
    L -->|No| M["403 Forbidden<br/>(insufficient permission)"]
    L -->|Yes| N["✅ Request proceeds"]

Cache Details

• Key format: admin:role:{clerkUserId}
• Namespace: RATE_LIMIT (shared KV namespace, uses admin: prefix)
• TTL: 300 seconds (5 minutes)
• Invalidation: Explicit delete on role assign/revoke via invalidateRoleCache()
• Stored value: JSON { role_name, permissions[], expires_at }

Middleware Pipeline

Admin routes are protected by middleware functions defined in worker/middleware/admin-role-middleware.ts. The pipeline runs in order:

flowchart LR
    A["requireAdminPermission(<br/>'config:write')"] --> B["verifyClerkJWT()"]
    B --> C["checkAdminRole()<br/>publicMetadata gate"]
    C --> D["resolveAdminContext()<br/>D1/KV role lookup"]
    D --> E["checkPermission()<br/>super-admin bypass<br/>or permission match"]
    E --> F["Handler executes"]

Guard Functions

Three middleware variants are exported for different use cases:

// Require a single permission
requireAdminPermission('config:write')

// Require at least one of several permissions (OR logic)
requireAnyAdminPermission(['config:write', 'tiers:write'])

// Require all listed permissions (AND logic)
requireAllAdminPermissions(['audit:read', 'metrics:read'])

There is also extractAdminContext() which resolves the caller’s role and permissions without enforcing a specific permission check. This is used by the “my context” endpoint.

AdminGuardResult

Every guard returns a discriminated union:

type AdminGuardResult =
    | { authorized: true; adminContext: ResolvedAdminContext }
    | { authorized: false; error: string; status: 401 | 403 };

Handlers check .authorized and return the appropriate HTTP status if access is denied.

Role Management API

Roles are managed via the admin API. Only users with the roles:write or roles:assign permission can modify roles.

Operation	Endpoint	Permission
List roles	GET /admin/system/roles	admin:read
Create role	POST /admin/system/roles	roles:write
Update role	PATCH /admin/system/roles/:id	roles:write
List assignments	GET /admin/system/roles/assignments	admin:read
Assign role	POST /admin/system/roles/assign	roles:assign
Revoke role	DELETE /admin/system/roles/revoke	roles:assign

Example: Assign a role

curl -X POST https://your-worker.workers.dev/admin/system/roles/assign \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "clerk_user_id": "user_2abc123",
    "role_name": "editor",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Example: Revoke a role

curl -X DELETE https://your-worker.workers.dev/admin/system/roles/revoke \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "clerk_user_id": "user_2abc123",
    "role_name": "editor"
  }'

Custom Roles

Beyond the three built-in roles, you can create custom roles with any combination of the 27 permissions:

curl -X POST https://your-worker.workers.dev/admin/system/roles \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "flag-manager",
    "display_name": "Flag Manager",
    "description": "Can manage feature flags but nothing else",
    "permissions": ["admin:read", "flags:read", "flags:write"]
  }'

Custom roles follow the same resolution flow and caching behavior as built-in roles.