A permission represents an individual access right that can be assigned to roles. Permissions define what actions users with a given role can perform within your application.
Permissions are defined at the environment level and can be assigned to both environment roles and custom roles. Each permission has a unique slug identifier that you use when assigning it to roles.
Get a list of all permissions in your WorkOS environment.
curl "https://api.workos.com/authorization/permissions" \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "list", "data": [ { "object": "permission", "id": "perm_01HXYZ123456789ABCDEFGHIJ", "slug": "documents:read", "name": "View Documents", "description": "Allows viewing document contents", "system": false, "resource_type_slug": "workspace", "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" } ], "list_metadata": { "before": "perm_01HXYZ123456789ABCDEFGHIJ", "after": "perm_01HXYZ987654321KJIHGFEDCBA" } }
| curl "https://api.workos.com/authorization/permissions" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const permissions = await workos.authorization.listPermissions(); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| permissions = workos_client.authorization.list_permissions() |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "object": "permission", | |
| "id": "perm_01HXYZ123456789ABCDEFGHIJ", | |
| "slug": "documents:read", | |
| "name": "View Documents", | |
| "description": "Allows viewing document contents", | |
| "system": false, | |
| "resource_type_slug": "workspace", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } | |
| ], | |
| "list_metadata": { | |
| "before": "perm_01HXYZ123456789ABCDEFGHIJ", | |
| "after": "perm_01HXYZ987654321KJIHGFEDCBA" | |
| } | |
| } |
GET/authorizationParameters Returns objectCreate a new permission in your WorkOS environment. The permission can then be assigned to environment roles and custom roles.
The slug must be unique within the environment and must be lowercase, containing only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
curl --request POST \ --url "https://api.workos.com/authorization/permissions" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "slug": "documents:read", "name": "View Documents", "description": "Allows viewing document contents", "resource_type_slug": "document" } BODY
{ "object": "permission", "id": "perm_01HXYZ123456789ABCDEFGHIJ", "slug": "documents:read", "name": "View Documents", "description": "Allows viewing document contents", "system": false, "resource_type_slug": "document", "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request POST \ | |
| --url "https://api.workos.com/authorization/permissions" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "slug": "documents:read", | |
| "name": "View Documents", | |
| "description": "Allows viewing document contents", | |
| "resource_type_slug": "document" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const permission = await workos.authorization.createPermission({ | |
| slug: 'documents:delete', | |
| name: 'Delete Documents', | |
| description: 'Allows deleting documents', | |
| }); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| permission = workos_client.authorization.create_permission( | |
| slug="documents:delete", | |
| name="Delete Documents", | |
| description="Allows deleting documents", | |
| ) |
| { | |
| "object": "permission", | |
| "id": "perm_01HXYZ123456789ABCDEFGHIJ", | |
| "slug": "documents:read", | |
| "name": "View Documents", | |
| "description": "Allows viewing document contents", | |
| "system": false, | |
| "resource_type_slug": "document", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST/authorizationReturns Retrieve a permission by its unique slug.
curl "https://api.workos.com/authorization/permissions/documents:read" \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "permission", "id": "perm_01HXYZ123456789ABCDEFGHIJ", "slug": "documents:read", "name": "View Documents", "description": "Allows viewing document contents", "system": false, "resource_type_slug": "workspace", "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl "https://api.workos.com/authorization/permissions/documents:read" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const permission = await workos.authorization.getPermission('documents:read'); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| permission = workos_client.authorization.get_permission(slug="documents:read") |
| { | |
| "object": "permission", | |
| "id": "perm_01HXYZ123456789ABCDEFGHIJ", | |
| "slug": "documents:read", | |
| "name": "View Documents", | |
| "description": "Allows viewing document contents", | |
| "system": false, | |
| "resource_type_slug": "workspace", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
GET/authorizationParameters Returns Update an existing permission. Only the fields provided in the request body will be updated.
curl --request PATCH \ --url "https://api.workos.com/authorization/permissions/documents:read" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "name": "View Documents", "description": "Allows viewing document contents" } BODY
{ "object": "permission", "id": "perm_01HXYZ123456789ABCDEFGHIJ", "slug": "documents:read", "name": "View Documents", "description": "Allows viewing document contents", "system": false, "resource_type_slug": "workspace", "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request PATCH \ | |
| --url "https://api.workos.com/authorization/permissions/documents:read" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "name": "View Documents", | |
| "description": "Allows viewing document contents" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const permission = await workos.authorization.updatePermission( | |
| 'documents:read', | |
| { | |
| name: 'View Documents', | |
| description: 'Allows viewing document contents', | |
| }, | |
| ); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| permission = workos_client.authorization.update_permission( | |
| slug="documents:read", | |
| name="View Documents", | |
| description="Allows viewing document contents", | |
| ) |
| { | |
| "object": "permission", | |
| "id": "perm_01HXYZ123456789ABCDEFGHIJ", | |
| "slug": "documents:read", | |
| "name": "View Documents", | |
| "description": "Allows viewing document contents", | |
| "system": false, | |
| "resource_type_slug": "workspace", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
PATCH/authorizationParameters Returns Delete an existing permission. System permissions cannot be deleted.
curl --request DELETE \ --url https://api.workos.com/authorization/permissions/documents:delete \ --header "Authorization: Bearer sk_example_123456789"
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); await workos.authorization.deletePermission('documents:delete');
from workos import WorkOSClient workos_client = WorkOSClient( api_key="sk_example_123456789", client_id="client_123456789" ) workos_client.authorization.delete_permission(slug="documents:delete")
DELETE/authorizationParameters Returns