Roles and RBAC

Shoehorn uses role-based access control (RBAC) powered by Cerbos to manage permissions. Roles determine what users can see and do in the platform.

Role Hierarchy

Tenant-Level Roles

Role	Description
`tenant:admin`	Full access to everything in the tenant
`tenant:viewer`	Read-only access to all resources

Resource-Specific Roles

Role	Permissions
Entity
`entity:viewer`	View and list entities
`entity:editor`	Create and update entities
`entity:admin`	Delete entities
Workflow
`workflow:viewer`	View and list workflows
`workflow:executor`	Create, execute, cancel own runs, retry own runs
`workflow:admin`	Delete workflows, cancel/retry any run
Mold (Template)
`mold:viewer`	View and list molds
`mold:editor`	Create and update own molds
`mold:publisher`	Publish molds
`mold:admin`	Delete molds
Operations
`operations:viewer`	View workloads and services
`operations:operator`	Update operations resources
`operations:admin`	Delete operations resources
Admin
`admin:viewer`	Read-only admin: view settings and analytics
`admin:operator`	Manage users, integrations, dashboards
Marketplace
`marketplace:viewer`	Browse marketplace
`marketplace:editor`	Install and configure items

Role Inheritance

Higher roles include all permissions of lower roles:

entity:admin  ->  entity:editor  ->  entity:viewer
workflow:admin  ->  workflow:executor  ->  workflow:viewer
mold:admin  ->  mold:publisher  ->  mold:editor  ->  mold:viewer
tenant:admin  ->  all resource roles

Assigning Roles

Via the UI

Navigate to Admin > Users
Select a user
Click Add Role
Select the role
Click Save

Via the API

# Add a role to a user
curl -X POST https://shoehorn.example.com/api/v1/admin/users/<user-id>/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "entity:editor"}'

# Remove a role from a user
curl -X DELETE https://shoehorn.example.com/api/v1/admin/users/<user-id>/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "entity:editor"}'

Listing Role Assignments

curl https://shoehorn.example.com/api/v1/admin/roles \
  -H "Authorization: Bearer <token>"

Returns all role assignments with user details.

Ownership-Based Access

Some operations are restricted by ownership:

Workflow cancel/retry: workflow:executor can only cancel or retry their own runs
Mold update: mold:editor can only update molds they created
workflow:admin and mold:admin can operate on any resource

How Authorization Works

User authenticates (OIDC session or API key)
Middleware extracts user roles from the database
For each request, Cerbos evaluates:
- User’s roles
- Target resource type and ID
- Requested action
- Tenant isolation (user’s tenant must match resource’s tenant)
Access is granted or denied

Authorization for API Keys

API keys use scope-based authorization instead of roles. See API Keys.

Fail-Closed Security

If a user has no roles assigned, all requests return 403 Forbidden. There are no implicit permissions.

RBAC Audit

There is no audit-log view in the UI yet. If you need an audit trail, enable pgaudit on the platform’s Postgres and query it directly. Role assignments and removals run through the same SQL writes pgaudit captures: who, when, what changed.

A UI surface for this is on the roadmap.