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 organization roles. Each permission has a unique slug identifier that you use when assigning it to roles.
{ "object": "permission", "id": "perm_01HXYZ123456789ABCDEFGHIJ", "slug": "documents:read", "name": "Read Documents", "description": "Allows reading documents", "system": false, "created_at": "2024-01-15T12:00:00.000Z", "updated_at": "2024-01-15T12:00:00.000Z" }
PermissionGet a list of all permissions in your WorkOS environment.
curl https://api.workos.com/authorization/permissions \ --header "Authorization: Bearer sk_example_123456789"
GET/authorizationParameters Returns objectCreate a new permission in your WorkOS environment. The permission can then be assigned to environment roles and organization 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:delete", "name": "Delete Documents", "description": "Allows deleting documents" } BODY
Retrieve a permission by its unique slug.
curl https://api.workos.com/authorization/permissions/documents:read \ --header "Authorization: Bearer sk_example_123456789"
GET/authorizationReturns 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
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"
DELETE/authorization