A custom role is an access control resource defined at the organization level. Custom roles allow individual organizations to create roles tailored to their specific needs, in addition to the environment roles that apply across all organizations.
Like environment roles, custom roles can be assigned to organization memberships, directory users, and SSO profiles. Each custom role has a unique slug identifier within the organization and can have permissions assigned to it.
When listing roles for an organization, both environment roles and custom roles are returned in priority order. Environment roles are included because they apply to all organizations in your environment.
Get a list of all roles that apply to an organization. This includes both environment roles and custom roles, returned in priority order.
curl "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles" \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "list", "data": [ { "slug": "admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Admin", "description": "Can manage all resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" } ] }
| curl "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const roles = await workos.authorization.listOrganizationRoles( | |
| 'org_01EHZNVPK3SFK441A1RGBFSHRT', | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.list_organization_roles(organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.list_organization_roles( | |
| organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().ListOrganizationRoles(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->listOrganizationRoles(organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.authorization.listOrganizationRoles("org_01EHZNVPK3SFK441A1RGBFSHRT"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.ListOrganizationRolesAsync("org_01EHZNVPK3SFK441A1RGBFSHRT"); |
| 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_organization_roles("org_01EHZNVPK3SFK441A1RGBFSHRT") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "slug": "admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Admin", | |
| "description": "Can manage all resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } | |
| ] | |
| } |
GET/authorizationParameters Returns Create a new custom role. The role will be specific to the organization and can be assigned to organization memberships.
The slug must be unique within the organization, begin with org-, and contain only lowercase letters, numbers, hyphens, and underscores.
New roles are placed at the bottom of the organization’s priority order.
curl --request POST \ --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "slug": "org-billing-admin", "name": "Billing Administrator", "description": "Can manage billing and invoices" } BODY
{ "slug": "org-billing-admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Billing Administrator", "description": "Can manage billing and invoices", "type": "OrganizationRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "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/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "slug": "org-billing-admin", | |
| "name": "Billing Administrator", | |
| "description": "Can manage billing and invoices" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.createOrganizationRole( | |
| 'org_01EHZNVPK3SFK441A1RGBFSHRT', | |
| { | |
| slug: 'org-billing-admin', | |
| name: 'Billing Administrator', | |
| description: 'Can manage billing and invoices', | |
| }, | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.create_organization_role( | |
| organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| name: "Billing Administrator" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.create_organization_role( | |
| organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", name="Billing Administrator" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().CreateOrganizationRole(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", &workos.AuthorizationCreateOrganizationRoleParams{ | |
| Name: "Billing Administrator", | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->createOrganizationRole( | |
| organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| name: "Billing Administrator", | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.authorization.AuthorizationApi.CreateOrganizationRoleOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreateOrganizationRoleOptions options = | |
| CreateOrganizationRoleOptions.builder().name("Billing Administrator").build(); | |
| workos.authorization.createOrganizationRole("org_01EHZNVPK3SFK441A1RGBFSHRT", options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.CreateOrganizationRoleAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| new AuthorizationCreateOrganizationRoleOptions { | |
| Name = "Billing Administrator", | |
| }); |
| use workos::Client; | |
| use workos::authorization::CreateOrganizationRoleParams; | |
| #[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_organization_role( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| CreateOrganizationRoleParams { | |
| name: "Billing Administrator".into(), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "slug": "org-billing-admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Billing Administrator", | |
| "description": "Can manage billing and invoices", | |
| "type": "OrganizationRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST/authorizationParameters Returns Retrieve a role that applies to an organization by its slug. This can return either an environment role or a custom role.
curl "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin" \ --header "Authorization: Bearer sk_example_123456789"
{ "slug": "org-billing-admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Billing Manager", "description": "Can view and export billing reports", "type": "OrganizationRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.getOrganizationRole( | |
| 'org_01EHZNVPK3SFK441A1RGBFSHRT', | |
| 'org-billing-admin', | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.get_organization_role( | |
| organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-billing-admin" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.get_organization_role( | |
| organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", slug="org-billing-admin" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().GetOrganizationRole(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-billing-admin") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->getOrganizationRole( | |
| organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-billing-admin", | |
| ); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.authorization.getOrganizationRole( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-billing-admin"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.GetOrganizationRoleAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", "org-billing-admin"); |
| 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_organization_role( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "org-billing-admin" | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "slug": "org-billing-admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Billing Manager", | |
| "description": "Can view and export billing reports", | |
| "type": "OrganizationRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
GET/authorizationParameters Returns Update an existing custom role. Only the fields provided in the request body will be updated.
curl --request PATCH \ --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "name": "Finance Administrator", "description": "Can manage all financial operations" } BODY
{ "slug": "org-billing-admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Finance Administrator", "description": "Can manage all financial operations", "type": "OrganizationRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "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/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "name": "Finance Administrator", | |
| "description": "Can manage all financial operations" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.updateOrganizationRole( | |
| 'org_01EHZNVPK3SFK441A1RGBFSHRT', | |
| 'org-billing-admin', | |
| { | |
| name: 'Finance Administrator', | |
| description: 'Can manage all financial operations', | |
| }, | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.update_organization_role( | |
| organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-billing-admin" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.update_organization_role( | |
| organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", slug="org-billing-admin" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().UpdateOrganizationRole(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-billing-admin") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->updateOrganizationRole( | |
| organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-billing-admin", | |
| ); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.authorization.updateOrganizationRole( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-billing-admin"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.UpdateOrganizationRoleAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", "org-billing-admin"); |
| 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_organization_role( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "org-billing-admin" | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "slug": "org-billing-admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Finance Administrator", | |
| "description": "Can manage all financial operations", | |
| "type": "OrganizationRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
PATCH/authorizationParameters Returns Delete an existing custom role. The role must not have any active assignments or IdP group role mappings.
If the role has active assignments, you will receive a 409 Conflict error with code role_has_assignments. If the role has group role mappings, you will receive a 409 Conflict error with code role_has_group_role_mappings.
curl --request DELETE \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin \ --header "Authorization: Bearer sk_example_123456789"
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); await workos.authorization.deleteOrganizationRole( 'org_01EHZNVPK3SFK441A1RGBFSHRT', 'org-billing-admin', );
require "workos" WorkOS.configure do |config| config.api_key = "sk_example_123456789" end WorkOS.client.authorization.delete_organization_role( organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT", slug: "org-admin" )
from workos import WorkOSClient client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") client.authorization.delete_organization_role( organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", slug="org-admin" )
package main import ( "context" "github.com/workos/workos-go/v9" ) func main() { client := workos.NewClient("sk_example_123456789") _, err := client.Authorization().DeleteOrganizationRole(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin") if err != nil { panic(err) } }
<?php use WorkOS\WorkOS; $workos = new WorkOS( apiKey: "sk_example_123456789", clientId: "client_123456789", ); $workos ->authorization() ->deleteOrganizationRole( organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT", slug: "org-admin", );
import com.workos.WorkOS; WorkOS workos = new WorkOS("sk_example_123456789"); workos.authorization.deleteOrganizationRole( "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin");
using WorkOS; var client = new WorkOSClient(new WorkOSOptions { ApiKey = "sk_example_123456789", ClientId = "client_123456789", }); await client.Authorization.DeleteOrganizationRoleAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin");
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_organization_role( "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin" ) .await?; Ok(()) }
DELETE/authorizationParameters Returns Replace all permissions assigned to a custom role. This operation removes any existing permissions and assigns the provided permissions.
To remove all permissions from a role, pass an empty array.
curl --request PUT \ --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-admin/permissions" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "permissions": [ "billing:read", "billing:write", "invoices:manage", "reports:view" ] } BODY
{ "slug": "org-admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Organization Admin", "description": "Can manage all resources", "type": "OrganizationRole", "resource_type_slug": "organization", "permissions": [ "billing:read", "billing:write", "invoices:manage", "reports:view" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request PUT \ | |
| --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-admin/permissions" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "permissions": [ | |
| "billing:read", | |
| "billing:write", | |
| "invoices:manage", | |
| "reports:view" | |
| ] | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.setOrganizationRolePermissions( | |
| 'org_01EHZNVPK3SFK441A1RGBFSHRT', | |
| 'org-billing-admin', | |
| { | |
| permissions: [ | |
| 'billing:read', | |
| 'billing:write', | |
| 'invoices:manage', | |
| 'reports:view', | |
| ], | |
| }, | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.set_organization_role_permissions( | |
| organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-admin", | |
| permissions: ["billing:read", "billing:write", "invoices:manage", "reports:view"] | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.set_organization_role_permissions( | |
| organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug="org-admin", | |
| permissions=["billing:read", "billing:write", "invoices:manage", "reports:view"], | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().SetOrganizationRolePermissions(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", &workos.AuthorizationSetOrganizationRolePermissionsParams{ | |
| Permissions: []any{"billing:read", "billing:write", "invoices:manage", "reports:view"}, | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->setOrganizationRolePermissions( | |
| organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-admin", | |
| permissions: [ | |
| "billing:read", | |
| "billing:write", | |
| "invoices:manage", | |
| "reports:view", | |
| ], | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.authorization.AuthorizationApi.SetOrganizationRolePermissionsOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| SetOrganizationRolePermissionsOptions options = | |
| SetOrganizationRolePermissionsOptions.builder() | |
| .permissions( | |
| List.of("billing:read", "billing:write", "invoices:manage", "reports:view")) | |
| .build(); | |
| workos.authorization.setOrganizationRolePermissions( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.SetOrganizationRolePermissionsAsync( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", | |
| new AuthorizationSetOrganizationRolePermissionsOptions { | |
| Permissions = new[] { "billing:read", "billing:write", "invoices:manage", "reports:view" }, | |
| }); |
| use workos::Client; | |
| use workos::authorization::SetOrganizationRolePermissionsParams; | |
| #[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() | |
| .set_organization_role_permissions( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "org-admin", | |
| SetOrganizationRolePermissionsParams { | |
| permissions: vec![ | |
| "billing:read".into(), | |
| "billing:write".into(), | |
| "invoices:manage".into(), | |
| "reports:view".into(), | |
| ], | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "slug": "org-admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Organization Admin", | |
| "description": "Can manage all resources", | |
| "type": "OrganizationRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "billing:read", | |
| "billing:write", | |
| "invoices:manage", | |
| "reports:view" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
PUT/authorizationParameters Returns Add a single permission to a custom role. If the permission is already assigned to the role, this operation has no effect.
curl --request POST \ --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-admin/permissions" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "slug": "reports:export" } BODY
{ "slug": "org-admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Organization Admin", "description": "Can manage all resources", "type": "OrganizationRole", "resource_type_slug": "organization", "permissions": [ "reports:export" ], "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/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-admin/permissions" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "slug": "reports:export" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.addOrganizationRolePermission( | |
| 'org_01EHZNVPK3SFK441A1RGBFSHRT', | |
| 'org-billing-admin', | |
| { permissionSlug: 'reports:export' }, | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.add_organization_role_permission( | |
| organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-admin", | |
| body_slug: "reports:export" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.add_organization_role_permission( | |
| organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug="org-admin", | |
| body_slug="reports:export", | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Authorization().AddOrganizationRolePermission(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", &workos.AuthorizationAddOrganizationRolePermissionParams{ | |
| Slug: "reports:export", | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->addOrganizationRolePermission( | |
| organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-admin", | |
| bodySlug: "reports:export", | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.authorization.AuthorizationApi.AddOrganizationRolePermissionOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| AddOrganizationRolePermissionOptions options = | |
| AddOrganizationRolePermissionOptions.builder().slug("reports:export").build(); | |
| workos.authorization.addOrganizationRolePermission( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.AddOrganizationRolePermissionAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", | |
| new AuthorizationAddOrganizationRolePermissionOptions { | |
| Slug = "reports:export", | |
| }); |
| use workos::Client; | |
| use workos::authorization::AddOrganizationRolePermissionParams; | |
| #[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() | |
| .add_organization_role_permission( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "org-admin", | |
| AddOrganizationRolePermissionParams { | |
| slug: "reports:export".into(), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "slug": "org-admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Organization Admin", | |
| "description": "Can manage all resources", | |
| "type": "OrganizationRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "reports:export" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST/authorizationParameters Returns Remove a single permission from a custom role by its slug.
curl --request DELETE \ --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-admin/permissions/documents:read" \ --header "Authorization: Bearer sk_example_123456789"
{ "slug": "admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Admin", "description": "Can manage all resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request DELETE \ | |
| --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-admin/permissions/documents:read" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.removeOrganizationRolePermission( | |
| 'org_01EHZNVPK3SFK441A1RGBFSHRT', | |
| 'org-billing-admin', | |
| 'reports:export', | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.authorization.remove_organization_role_permission( | |
| organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-admin", | |
| permission_slug: "documents:read" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.authorization.remove_organization_role_permission( | |
| organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug="org-admin", | |
| 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().RemoveOrganizationRolePermission(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", "documents:read") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->authorization() | |
| ->removeOrganizationRolePermission( | |
| organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| slug: "org-admin", | |
| permissionSlug: "documents:read", | |
| ); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.authorization.removeOrganizationRolePermission( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", "documents:read"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Authorization.RemoveOrganizationRolePermissionAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", "org-admin", | |
| "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() | |
| .remove_organization_role_permission( | |
| "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "org-admin", | |
| "documents:read" | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "slug": "admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Admin", | |
| "description": "Can manage all resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
DELETE/authorizationParameters Returns