Concepts · reference
System permissions
The full catalogue of Authio's system permissions. Mirrors WorkOS's set so a customer migrating between the two never has to re-slug their roles.
Every Authio customer-tenant project is seeded with the twelve system permissions below on creation (migration 0061_roles_permissions.sql). System permissions are flagged is_system = true and the management API refuses to delete them; you can rename them (display name + description) but the slug is immutable so SDK code that gates on the literal slug never breaks.
The seeded admin role gets all twelve system permissions attached. Edit the role in /roles/admin if you want to drop one in your own deployment — the system flag protects the permission, not its assignment to the admin role.
Catalogue
| Slug | Name | What it grants |
|---|---|---|
| organizations:manage | Manage organizations | Create, edit, and delete organizations. |
| organizations:read | Read organizations | View organization details. |
| users:manage | Manage users | Create, edit, and delete users. |
| users:read | Read users | View user details. |
| sso-connections:manage | Manage SSO connections | Configure SAML / OIDC SSO connections for any organization. |
| dsync:manage | Manage directory sync | Configure SCIM directory sync for any organization. |
| domains:manage | Manage domains | Add or remove organization-claim domains. |
| audit-log-streams:manage | Manage audit log streams | Configure audit-log stream destinations (Datadog, S3, generic webhook). |
| api-keys:manage | Manage API keys | Manage API keys for the project. At GA this is equivalent to api-keys:manage-self. |
| api-keys:manage-self | Manage own API keys | Manage API keys created by the calling user. |
| api-keys:manage-all | Manage all API keys | Manage API keys for any user in the project. |
| pipes:manage | Manage pipes | Configure third-party OAuth connector pipes (the WorkOS-compatible Pipes surface). |
Mapping to WorkOS
The twelve slugs above are byte-identical to the WorkOS system permission set documented at workos.com/docs/user-management/roles-permissions. A customer migrating from WorkOS to Authio can ship the same role ↔ permission assignments without touching application code that gates on permissions.includes(...).
Adding custom permissions
Custom permissions are first-class. The slug format mirrors the system shape — lowercase, colons + hyphens, 1–64 chars. See the Roles and permissions page for the create flow.