WorkOS Roles & Permissions API Reference

Step 1: Fetch Documentation

STOP. WebFetch the relevant docs for latest implementation details before proceeding.

• https://workos.com/docs/reference/roles

• https://workos.com/docs/reference/roles/organization-role

• https://workos.com/docs/reference/roles/organization-role/add-permission

• https://workos.com/docs/reference/roles/organization-role/create

• https://workos.com/docs/reference/roles/organization-role/delete

• https://workos.com/docs/reference/roles/organization-role/get

• https://workos.com/docs/reference/roles/organization-role/list

• https://workos.com/docs/reference/roles/organization-role/remove-permission

Authentication Setup

All API requests require authentication via Bearer token:

Authorization: Bearer sk_live_your_api_key

Set your API key as an environment variable:

export WORKOS_API_KEY=sk_live_your_api_key

Endpoint Catalog

Organization Roles (Per-Organization Role Management)

Method Endpoint Purpose

POST /user_management/organization_roles

Create a role for a specific organization

GET /user_management/organization_roles/:id

Get a single organization role

GET /user_management/organization_roles

List roles for an organization

PUT /user_management/organization_roles/:id

Update organization role metadata

DELETE /user_management/organization_roles/:id

Delete an organization role

POST /user_management/organization_roles/:id/add_permission

Add permission to organization role

POST /user_management/organization_roles/:id/remove_permission

Remove permission from organization role

POST /user_management/organization_roles/:id/set_permissions

Replace all permissions for organization role

Global Roles (Reusable Role Templates)

Method Endpoint Purpose

POST /user_management/roles

Create a reusable role template

GET /user_management/roles/:id

Get a single role template

GET /user_management/roles

List all role templates

PUT /user_management/roles/:id

Update role template metadata

POST /user_management/roles/:id/add_permission

Add permission to role template

POST /user_management/roles/:id/set_permissions

Replace all permissions for role template

Permissions (Granular Access Controls)

Method Endpoint Purpose

POST /user_management/permissions

Create a permission

GET /user_management/permissions/:id

Get a single permission

GET /user_management/permissions

List all permissions

PUT /user_management/permissions/:id

Update permission metadata

DELETE /user_management/permissions/:id

Delete a permission

Operation Decision Tree

When to Use Organization Roles vs Global Roles

Need to define a role? │ ├─ Is this role specific to ONE organization? │ └─ Use Organization Roles API (POST /organization_roles) │ - Examples: "Acme Corp Admin", "Beta Org Viewer" │ └─ Is this role reusable across ALL organizations? └─ Use Global Roles API (POST /roles) - Examples: "Admin", "Member", "Viewer" - Note: Global roles are templates — assign them to organizations separately

CRUD Operation Mapping

Create a new permission:

POST /user_management/permissions

Create a role template (multi-organization):

POST /user_management/roles

Create a role for specific organization:

POST /user_management/organization_roles

Update role metadata (name, description):

PUT /user_management/roles/:id # For global roles PUT /user_management/organization_roles/:id # For org-specific roles

Add/remove permissions incrementally:

POST /organization_roles/:id/add_permission # Add one permission POST /organization_roles/:id/remove_permission # Remove one permission

Replace all permissions at once:

POST /organization_roles/:id/set_permissions # Replaces entire permission set POST /roles/:id/set_permissions # For global roles

Delete role (WARNING: affects assigned users):

DELETE /user_management/organization_roles/:id

Request/Response Patterns

Create Organization Role

Request:

curl -X POST https://api.workos.com/user_management/organization_roles
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d '{ "organization_id": "org_01H5K8PJZ8N4JKQ6X1Y9Z2ABC", "name": "Engineering Manager", "description": "Manages engineering team members" }'

Response (201):

{ "object": "organization_role", "id": "org_role_01H5K8PJZ8N4JKQ6X1Y9Z2DEF", "organization_id": "org_01H5K8PJZ8N4JKQ6X1Y9Z2ABC", "name": "Engineering Manager", "description": "Manages engineering team members", "permissions": [], "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }

Add Permission to Role

Request:

curl -X POST https://api.workos.com/user_management/organization_roles/org_role_01H5K8PJZ8N4JKQ6X1Y9Z2DEF/add_permission
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d '{ "permission_id": "perm_01H5K8PJZ8N4JKQ6X1Y9Z2GHI" }'

Response (200):

{ "object": "organization_role", "id": "org_role_01H5K8PJZ8N4JKQ6X1Y9Z2DEF", "permissions": [ { "id": "perm_01H5K8PJZ8N4JKQ6X1Y9Z2GHI", "name": "repo:write", "description": "Write access to repositories" } ] }

Set All Permissions (Replace Existing)

Request:

curl -X POST https://api.workos.com/user_management/organization_roles/org_role_01H5K8PJZ8N4JKQ6X1Y9Z2DEF/set_permissions
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d '{ "permission_ids": [ "perm_01H5K8PJZ8N4JKQ6X1Y9Z2GHI", "perm_01H5K8PJZ8N4JKQ6X1Y9Z2JKL" ] }'

Response (200):

{ "object": "organization_role", "id": "org_role_01H5K8PJZ8N4JKQ6X1Y9Z2DEF", "permissions": [ { "id": "perm_01H5K8PJZ8N4JKQ6X1Y9Z2GHI", "name": "repo:write" }, { "id": "perm_01H5K8PJZ8N4JKQ6X1Y9Z2JKL", "name": "user:invite" } ] }

List Organization Roles (Paginated)

Request:

curl -X GET "https://api.workos.com/user_management/organization_roles?organization_id=org_01H5K8PJZ8N4JKQ6X1Y9Z2ABC&limit=10"
-H "Authorization: Bearer ${WORKOS_API_KEY}"

Response (200):

{ "object": "list", "data": [ { "object": "organization_role", "id": "org_role_01H5K8PJZ8N4JKQ6X1Y9Z2DEF", "name": "Engineering Manager", "permissions": [...] } ], "list_metadata": { "before": null, "after": "org_role_01H5K8PJZ8N4JKQ6X1Y9Z2XYZ" } }

Create Permission

Request:

curl -X POST https://api.workos.com/user_management/permissions
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d '{ "name": "repo:delete", "description": "Delete repositories" }'

Response (201):

{ "object": "permission", "id": "perm_01H5K8PJZ8N4JKQ6X1Y9Z2MNO", "name": "repo:delete", "description": "Delete repositories", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }

Pagination Handling

List endpoints use cursor-based pagination:

Initial request:

curl "https://api.workos.com/user_management/roles?limit=10"

Next page (using after cursor):

curl "https://api.workos.com/user_management/roles?limit=10&after=role_01H5K8PJZ8N4JKQ6X1Y9Z2XYZ"

Previous page (using before cursor):

curl "https://api.workos.com/user_management/roles?limit=10&before=role_01H5K8PJZ8N4JKQ6X1Y9Z2ABC"

The list_metadata object contains before and after cursors. A null cursor indicates no more pages in that direction.

Error Code Mapping

Status Code Cause Fix

400 Invalid organization_id format Verify organization ID starts with org_

400 Missing required field (e.g., name ) Check request body includes all required fields

401 Invalid or missing API key Verify Authorization: Bearer sk_live_... header

403 API key lacks required permissions Check API key permissions in WorkOS Dashboard

404 Role ID or permission ID not found Verify resource exists via GET request first

409 Permission already assigned to role Use set_permissions to replace, or skip if acceptable

409 Permission name already exists Choose a unique permission name

422 Invalid permission_id format Ensure permission ID starts with perm_

429 Rate limit exceeded Implement exponential backoff (start with 1s delay)

500 Internal server error Retry with exponential backoff, contact support if persists

Common Error Response Format

{ "error": "invalid_request", "error_description": "organization_id is required", "code": "invalid_request" }

Runnable Verification Commands

1. Create a Permission

export WORKOS_API_KEY=sk_live_your_key_here

PERMISSION_ID=$(curl -s -X POST https://api.workos.com/user_management/permissions
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d '{"name":"test:read","description":"Test read permission"}'
| jq -r '.id')

echo "Created permission: $PERMISSION_ID"

2. Create an Organization Role

export ORG_ID=org_your_org_id_here

ROLE_ID=$(curl -s -X POST https://api.workos.com/user_management/organization_roles
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d "{"organization_id":"$ORG_ID","name":"Test Role","description":"Test role"}"
| jq -r '.id')

echo "Created role: $ROLE_ID"

3. Add Permission to Role

curl -X POST https://api.workos.com/user_management/organization_roles/$ROLE_ID/add_permission
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d "{"permission_id":"$PERMISSION_ID"}"

4. Verify Role Has Permission

curl -s -X GET https://api.workos.com/user_management/organization_roles/$ROLE_ID
-H "Authorization: Bearer ${WORKOS_API_KEY}"
| jq '.permissions'

5. Cleanup (Delete Role)

curl -X DELETE https://api.workos.com/user_management/organization_roles/$ROLE_ID
-H "Authorization: Bearer ${WORKOS_API_KEY}"

Rate Limits

• Default limit: 100 requests per 10 seconds per API key

• Retry strategy: Implement exponential backoff starting at 1 second

• 429 response includes: Retry-After header (seconds to wait)

Example retry logic:

If 429 received, extract Retry-After header

RETRY_AFTER=$(curl -i ... | grep -i retry-after | awk '{print $2}') sleep $RETRY_AFTER

Retry request

Related Skills

• workos-rbac — Role-Based Access Control feature guide (how to design permission systems)

• workos-api-organization — Organization management API (required for organization roles)

• workos-api-authkit — User management API (assign roles to users)