Roles and Permissions
Koldan uses a Role-Based Access Control (RBAC) system to manage what users and API keys can do. Every authenticated identity - whether a signed-in user or an API key - is associated with a role, and that role determines the set of permission scopes it holds.
Roles
A role is a named collection of permission scopes. Koldan ships with a set of system roles that cover common access patterns, and administrators can create custom roles for more granular control.
System Roles
System roles are built into every Koldan installation and cannot be deleted or renamed. They serve as the default building blocks for access control and follow a strict pyramid - each role is a superset of all roles below it.
| Role | Slug | Hierarchy | Description |
|---|---|---|---|
| Admin | admin |
100 | Full platform control - tenant management, role creation, and subscription plan administration. |
| Operator | operator |
85 | Platform operations - model, preset, and language management plus write access to quotas, retention, and rate limits. |
| Manager | manager |
75 | User administration - impersonation and write access to user accounts and profiles. |
| Supervisor | supervisor |
65 | Read-only admin oversight - view users, roles, quotas, retention, rate limits, and audit logs. |
| Team Lead | team-lead |
60 | Team leadership - workspace management, prompt administration, profile and log access. |
| User | user |
50 | Standard access - upload files, create transcription/translation/summary jobs, delete own resources, and view results. |
| Member | member |
35 | Collaborative team member - create content, manage prompts, look up users. Cannot delete speech content. |
| Viewer | viewer |
25 | Read-only access to resources. Can create and manage own API keys. |
First user and default role
When a new tenant is created, the first user who logs in is automatically assigned the Admin role. All subsequent users receive the Viewer role by default. Administrators can change the default role in the tenant settings.
Custom Roles
Work in Progress
Custom Roles are not yet available. This feature is currently under development and will be enabled in a future release.
Administrators can create custom roles to tailor access beyond the system roles. A custom role:
- Has a unique slug (URL-safe identifier) and a human-readable name.
- Contains a hand-picked set of scopes selected from the full permission catalog.
- Has a hierarchy order that determines its privilege level relative to other roles.
- Can be modified or deleted at any time (unlike system roles).
Scope ceiling rule
A custom role can only include scopes that the creator's own role already has. You cannot grant permissions you don't have yourself. The same rule applies when creating scoped API keys.
For the API to create and manage custom roles, see the Admin Roles API reference.
Role Hierarchy
Every role has a hierarchy order - a numeric value that indicates its privilege level. Higher numbers mean more privileged:
Admin (100) > Operator (85) > Manager (75) > Supervisor (65) > Team Lead (60) > User (50) > Member (35) > Viewer (25)
The hierarchy enforces two rules:
- Assignment constraint - you can only assign roles with a hierarchy order equal to or lower than your own. An Admin can assign any role; a Manager cannot assign Operator or Admin.
- Custom role ceiling - when creating a custom role, its hierarchy order must be lower than the creator's role hierarchy.
Permission Scopes
Scope Format
Every scope follows the service:resource:action naming convention:
| Part | Description | Examples |
|---|---|---|
| Service | The top-level domain or feature area | speech, ai, admin, user, desktop |
| Resource | The entity being accessed | files, transcriptions, prompts, roles, users |
| Action | The operation being performed | read, write, delete, admin |
For example, speech:transcriptions:write grants the ability to create and modify transcriptions within the Speech Services domain.
Scope Reference
The table below lists all available permission scopes, organized by domain. Each role inherits all permissions from the roles below it in the pyramid.
Speech Services
| Scope | Description | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|---|
speech:files:read |
Read uploaded audio files | ||||||||
speech:files:write |
Upload and modify audio files | ||||||||
speech:files:delete |
Delete audio files | ||||||||
speech:files:share |
Share files with other users and manage file shares | ||||||||
speech:transcriptions:read |
Read transcription results | ||||||||
speech:transcriptions:write |
Create and modify transcriptions | ||||||||
speech:transcriptions:delete |
Delete transcriptions | ||||||||
speech:translations:read |
Read translation results | ||||||||
speech:translations:write |
Create and modify translations | ||||||||
speech:translations:delete |
Delete translations | ||||||||
speech:summaries:read |
Read summary results | ||||||||
speech:summaries:write |
Create and modify summaries | ||||||||
speech:summaries:delete |
Delete summaries | ||||||||
speech:sessions:read |
View streaming session history and segments | ||||||||
speech:sessions:write |
Create online streaming sessions | ||||||||
speech:sessions:delete |
Delete streaming sessions and purge content | ||||||||
speech:models:read |
List and view model details | ||||||||
speech:models:download |
Download model binary files | ||||||||
speech:model-aliases:read |
List and view model alias details | ||||||||
speech:presets:read |
List and retrieve presets | ||||||||
speech:presets:write |
Create and update presets | ||||||||
speech:presets:delete |
Delete presets | ||||||||
speech:languages:read |
List and retrieve languages | ||||||||
speech:languages:write |
Create and update languages | ||||||||
speech:languages:delete |
Delete languages |
AI Services
| Scope | Description | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|---|
ai:prompts:read |
List and retrieve prompt templates | ||||||||
ai:prompts:write |
Create, update, and assign prompt templates | ||||||||
ai:prompts:delete |
Delete and unassign prompt templates | ||||||||
ai:prompts:admin |
Manage tenant-wide prompt templates and administer assignments |
User & Account
| Scope | Description | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|---|
user:apikeys:read |
List and view own API keys | ||||||||
user:apikeys:write |
Create API keys | ||||||||
user:apikeys:delete |
Revoke own API keys | ||||||||
users:lookup |
Search and look up tenant users for collaboration |
Subscriptions
| Scope | Description | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|---|
subscriptions:plans:read |
List and view subscription plans | ||||||||
subscriptions:read |
View own subscription |
Workspace
| Scope | Description | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|---|
workspace:create |
Create new workspaces | ||||||||
workspace:manage |
Manage workspace settings and members | ||||||||
workspace:delete |
Delete workspaces |
Desktop Application
| Scope | Description | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|---|
desktop:app:use |
Use the Koldan desktop application | ||||||||
desktop:logs:read |
Search and download logs | ||||||||
desktop:profiles:read |
View any user profile and preferences | ||||||||
desktop:profiles:write |
Update any user profile and preferences |
Administration
| Scope | Description | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|---|
admin:roles:read |
View roles and role assignments | ||||||||
admin:roles:write |
Create, update, and assign roles | ||||||||
admin:users:read |
View user profiles, assignments, subscriptions, and quotas | ||||||||
admin:users:write |
Manage user accounts, role assignments, subscriptions, and quotas | ||||||||
admin:tenants:read |
List and view tenants | ||||||||
admin:tenants:write |
Create, update, enable/disable tenants | ||||||||
admin:quotas:read |
View tenant quotas and usage | ||||||||
admin:quotas:write |
Manage tenant quotas | ||||||||
admin:retention:read |
View data retention policies | ||||||||
admin:retention:write |
Manage data retention policies | ||||||||
admin:models:write |
Upload and configure models | ||||||||
admin:models:delete |
Delete models | ||||||||
admin:model-aliases:write |
Create and update model aliases | ||||||||
admin:model-aliases:delete |
Delete model aliases | ||||||||
admin:ratelimits:read |
View tenant rate limit defaults and user rate limits | ||||||||
admin:ratelimits:write |
Manage tenant rate limit defaults and user rate limit overrides | ||||||||
admin:subscriptions:plans:read |
View all subscription plans including inactive | ||||||||
admin:subscriptions:plans:write |
Create, update, and deactivate subscription plans | ||||||||
admin:audit:read |
View audit log records | ||||||||
admin:impersonate |
Impersonate another user to view the platform as that user |
Role Assignment
How Users Get Their Role
When a user signs in to a tenant for the first time, Koldan automatically assigns them the tenant's default role (typically Viewer). The very first user on a new tenant receives the first-login role (typically Admin).
After the initial assignment, an administrator can change any user's role through the Admin Users API.
One Role per Tenant
Each user has exactly one role within a given tenant. If a user has access to multiple tenants (Koldan Cloud), they may have a different role in each.
API Key Scopes
When an API key is created with explicit scopes, the requested scopes must be a subset of the creator's role permissions - you cannot grant a key more access than you have yourself. At runtime, the key's effective permissions are the intersection of its scopes and the user's current role permissions, so if the user's role is later downgraded, the key automatically loses any permissions the user no longer has.
When an API key is created without scopes, it becomes an identity-only key. Identity-only keys provide authentication only (the system knows who is calling) but carry no authorization scopes - any endpoint that requires a specific scope will reject the request with 403 Forbidden.
For more details on API key authentication and scoped keys, see Authentication and API Keys.
Quick Reference: Role Comparison
The table below summarizes what each system role can do at a high level. Each role inherits all capabilities from the roles below it.
| Capability | Admin | Operator | Manager | Supervisor | Team Lead | User | Member | Viewer |
|---|---|---|---|---|---|---|---|---|
| View files, transcriptions, translations, summaries | ||||||||
| Create and manage own API keys | ||||||||
| Use the desktop application | ||||||||
| Create content (upload, transcribe, translate, summarize) | ||||||||
| Look up other users in tenant | ||||||||
| Manage own prompt templates | ||||||||
| Delete own speech content | ||||||||
| Manage workspaces and workspace members | ||||||||
| Manage prompt templates tenant-wide | ||||||||
| View and download desktop logs | ||||||||
| View and manage user profiles | ||||||||
| View users, roles, quotas, retention, rate limits (read-only) | ||||||||
| View audit logs | ||||||||
| Manage user accounts and impersonate users | ||||||||
| Manage models, aliases, presets, and languages | ||||||||
| Write quotas, retention policies, and rate limits | ||||||||
| View admin subscription plans | ||||||||
| Manage tenants | ||||||||
| Create and manage roles | ||||||||
| Manage subscription plans |