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(); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.list_permissions |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.list_permissions() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().ListPermissions(context.Background()) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->authorization()->listPermissions(); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.authorization.listPermissions(); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.ListPermissionsAsync(); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .authorization() | |
| .list_permissions() | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "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', | |
| }); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.create_permission( | |
| slug: "documents:read", | |
| name: "View Documents" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.create_permission(slug="documents:read", name="View Documents") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().CreatePermission(context.Background(), &workos.AuthorizationCreatePermissionParams{ | |
| Slug: "documents:read", | |
| Name: "View Documents", | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->createPermission(slug: "documents:read", name: "View Documents"); |
| import com.workos.WorkOS; | |
| import com.workos.authorization.AuthorizationApi.CreatePermissionOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreatePermissionOptions options = CreatePermissionOptions.builder() | |
| .slug("documents:read") | |
| .name("View Documents") | |
| .build(); | |
| workos.authorization.createPermission(options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.CreatePermissionAsync(new AuthorizationCreatePermissionOptions { | |
| Slug = "documents:read", | |
| Name = "View Documents", | |
| }); |
| use workos::Client; | |
| use workos::authorization::CreatePermissionParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .authorization() | |
| .create_permission( | |
| CreatePermissionParams { | |
| slug: "documents:read".into(), | |
| name: "View Documents".into(), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "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'); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.get_permission(slug: "documents:read") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.get_permission(slug="documents:read") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().GetPermission(context.Background(), "documents:read") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->authorization()->getPermission(slug: "documents:read"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.authorization.getPermission("documents:read"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.GetPermissionAsync("documents:read"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .authorization() | |
| .get_permission("documents:read") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "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', | |
| }, | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.update_permission(slug: "documents:read") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.update_permission(slug="documents:read") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().UpdatePermission(context.Background(), "documents:read") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->authorization()->updatePermission(slug: "documents:read"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.authorization.updatePermission("documents:read"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.UpdatePermissionAsync("documents:read"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .authorization() | |
| .update_permission("documents:read") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "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');
require "workos" WorkOS.configure do |config| config.api_key = "sk_example_123456789" end WorkOS.client.authorization.delete_permission(slug: "documents:read")
from workos import WorkOSClient client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") client.authorization.delete_permission(slug="documents:read")
package main import ( "context" "github.com/workos/workos-go/v9" ) func main() { client := workos.NewClient("sk_example_123456789") _, err := client.Authorization().DeletePermission(context.Background(), "documents:read") if err != nil { panic(err) } }
<?php use WorkOS\WorkOS; $workos = new WorkOS( apiKey: "sk_example_123456789", clientId: "client_123456789", ); $workos->authorization()->deletePermission(slug: "documents:read");
import com.workos.WorkOS; WorkOS workos = new WorkOS("sk_example_123456789"); workos.authorization.deletePermission("documents:read");
using WorkOS; var client = new WorkOSClient(new WorkOSOptions { ApiKey = "sk_example_123456789", ClientId = "client_123456789", }); await client.Authorization.DeletePermissionAsync("documents:read");
use workos::Client; #[tokio::main] async fn main() -> Result<(), workos::Error> { let client = Client::builder() .api_key("sk_example_123456789") .client_id("client_123456789") .build(); let _result = client .authorization() .delete_permission("documents:read") .await?; Ok(()) }
DELETE/authorizationParameters Returns