RBAC Permission Matrix
Role-Based Access Control for HermesX SaaS API
Roles are assigned per API Key. A key can hold multiple roles.
Roles
| Role |
Description |
Scope |
super_admin |
Platform operator |
Cross-tenant, all operations |
admin |
Legacy break-glass compatibility grant |
Explicitly granted admin APIs only |
owner |
Tenant owner |
Own tenant, management + execution |
user |
Regular user |
Own tenant, execution + self-data |
auditor |
Read-only compliance |
Own tenant, read audit/receipts |
platform_admin |
Platform operator |
Cross-tenant governance |
security_admin |
Security operator |
Secrets, safety, egress, sharing rollback |
billing_admin |
Billing operator |
Pricing and usage |
ops_admin |
Operations operator |
Sandbox, runtime, egress |
tenant_admin |
Tenant operator |
Tenant-local administration |
Permission Matrix
Resource: Tenants
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| List all tenants |
Yes |
— |
— |
— |
— |
| Get own tenant |
Yes |
Yes |
Yes |
— |
— |
| Create tenant |
Yes |
— |
— |
— |
— |
| Update tenant |
Yes |
Yes |
— |
— |
— |
| Delete tenant |
Yes |
— |
— |
— |
— |
Resource: API Keys
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| Create (any tenant) |
Yes |
— |
— |
— |
— |
| Create (own tenant) |
Yes |
Yes |
Yes |
— |
— |
| List (own tenant) |
Yes |
Yes |
Yes |
— |
— |
| Revoke (own tenant) |
Yes |
Yes |
Yes |
— |
— |
| Rotate |
Yes |
Yes |
Yes |
— |
— |
Resource: Sessions
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| Create |
Yes |
Yes |
Yes |
Yes |
— |
| List (all in tenant) |
Yes |
Yes |
Yes |
— |
— |
| List (own) |
Yes |
Yes |
Yes |
Yes |
— |
| Get |
Yes |
Yes |
Yes |
Yes* |
Yes |
| Delete |
Yes |
Yes |
Yes |
— |
— |
*user can only access own sessions
Resource: Chat Completions
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| POST /v1/chat/completions |
Yes |
Yes |
Yes |
Yes |
— |
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| Execute (allowed) |
Yes |
Yes |
Yes |
Yes |
— |
| Execute (any) |
Yes |
Yes |
— |
— |
— |
| Configure sandbox |
Yes |
Yes |
— |
— |
— |
Resource: Memories
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| Set (own) |
Yes |
Yes |
Yes |
Yes |
— |
| Get (own) |
Yes |
Yes |
Yes |
Yes |
— |
| List (tenant) |
Yes |
Yes |
Yes |
— |
— |
| Delete (own) |
Yes |
Yes |
Yes |
Yes |
— |
| Delete (any in tenant) |
Yes |
Yes |
— |
— |
— |
Resource: Audit Logs
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| List (own tenant) |
Yes |
Yes |
— |
— |
Yes |
| Export |
Yes |
Yes |
— |
— |
Yes |
Resource: Execution Receipts
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| List (own tenant) |
Yes |
Yes |
— |
— |
Yes |
| Get by ID |
Yes |
Yes |
— |
— |
Yes |
Resource: Usage / Metering
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| Query (own tenant) |
Yes |
Yes |
Yes |
— |
Yes |
| Query (cross-tenant) |
Yes |
— |
— |
— |
— |
Resource: GDPR
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| Export tenant data |
Yes |
Yes |
— |
— |
— |
| Delete tenant data |
Yes |
Yes |
— |
— |
— |
Resource: Sandbox Policy
| Operation |
super_admin |
admin |
owner |
user |
auditor |
| Get |
Yes |
Yes |
Yes |
— |
— |
| Update |
Yes |
Yes |
— |
— |
— |
Resource: Evolution Sharing
| Operation |
Required Scope |
| Get global sharing policy |
sharing:read or security:read |
| Update global sharing policy |
sharing:write or security:write |
| Get tenant sharing policy |
sharing:read or tenant:read |
| Update tenant sharing policy |
sharing:write or tenant:write |
| Revoke shared knowledge |
sharing:write or security:write |
Route-to-Role Mapping
Current enforcement in cmd/hermesx/saas.go:
Default role: user (all routes accessible unless overridden)
Admin-gated routes:
/v1/tenants → admin
/v1/tenants/ → admin
/v1/api-keys → admin
/v1/api-keys/ → admin
/v1/gdpr/ → admin
Auditor-gated routes:
GET /v1/audit-logs → auditor
/v1/execution-receipts → auditor
Admin /admin/v1/* routes are additionally guarded by domain scopes in internal/api/admin/handler.go. The explicit admin scope is accepted as break-glass compatibility, but empty legacy scopes are rejected for Admin domain routes.
Scope Model
Scopes provide fine-grained access within a role:
| Scope |
Grants |
admin |
Full administrative access |
tenant:read / tenant:write |
Tenant lifecycle and tenant-scoped policy management |
key:read / key:write |
API key lifecycle |
billing:read / billing:write |
Pricing and usage controls |
usage:read / usage:read:all |
Tenant usage and cross-tenant aggregate usage |
audit:read |
Audit logs and execution receipts |
channel:read / channel:write |
Trusted channel app configuration and channel binding governance |
security:read / security:write |
Secrets, safety, egress, and sharing security controls |
ops:read / ops:write |
Runtime and sandbox operations |
sharing:read / sharing:write |
Evolution shared learning policy and rollback |
read |
Read operations on all accessible resources |
write |
Create/update operations |
execute |
Tool and chat execution |
audit |
Read audit logs and execution receipts |
gdpr |
Data export and deletion |
Legacy Key Behavior
Keys with empty scopes (pre-scope migration):
- Allowed: read, write, execute
- Denied: admin (must be explicitly granted)
Tenant Boundary Rules
- Non-admin callers:
tenant_id always derived from credential context
- Admin callers: May specify
tenant_id in request body for cross-tenant operations
- Body-supplied tenant_id: Only honored when
AuthContext.HasRole("admin") or HasRole("super_admin")
- X-Tenant-ID header: NEVER trusted for tenant derivation (ignored by middleware)
- Channel OAuth callers: Public
/auth/channel/* routes never accept tenant_id; tenant is resolved from channel_apps.platform + app_key