SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsworkos

workos

Coding & development

View repository

Updated 10-16 02:36

About this skill

Troubleshooting

If requests fail, run zero doctor check-connector --env-name WORKOS_TOKEN or zero doctor check-connector --url https://api.workos.com/organizations --method GET

Authentication

All requests require a secret API key passed as a Bearer token:

Authorization: Bearer $WORKOS_TOKEN

Official docs: https://workos.com/docs/reference

Environment Variables

Variable Description
WORKOS_TOKEN WorkOS secret API key (sk_live_... or sk_test_...)

Key Endpoints

Base URL: https://api.workos.com

Organizations

List Organizations

curl -s "https://api.workos.com/organizations" --header "Authorization: Bearer $WORKOS_TOKEN"

Response includes a data array of organization objects, each with id, name, domains, and created_at.

Get Organization

curl -s "https://api.workos.com/organizations/<organization-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Create Organization

Write to /tmp/workos_org.json:

{
  "name": "<your-organization-name>",
  "domains": ["<your-domain.com>"]
}

curl -s -X POST "https://api.workos.com/organizations" --header "Authorization: Bearer $WORKOS_TOKEN" --header "Content-Type: application/json" -d @/tmp/workos_org.json

Delete Organization

curl -s -X DELETE "https://api.workos.com/organizations/<organization-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

SSO Connections

List SSO Connections

curl -s "https://api.workos.com/connections" --header "Authorization: Bearer $WORKOS_TOKEN"

Filter by organization:

curl -s "https://api.workos.com/connections?organization_id=<organization-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Get SSO Connection

curl -s "https://api.workos.com/connections/<connection-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Delete SSO Connection

curl -s -X DELETE "https://api.workos.com/connections/<connection-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Directory Sync (SCIM)

List Directories

curl -s "https://api.workos.com/directories" --header "Authorization: Bearer $WORKOS_TOKEN"

Filter by organization:

curl -s "https://api.workos.com/directories?organization_id=<organization-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Get Directory

curl -s "https://api.workos.com/directories/<directory-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

List Directory Users

curl -s "https://api.workos.com/directory_users?directory=<directory-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Response includes a data array of directory user objects with id, username, emails, first_name, last_name, state, and group memberships.

Get Directory User

curl -s "https://api.workos.com/directory_users/<directory-user-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

List Directory Groups

curl -s "https://api.workos.com/directory_groups?directory=<directory-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Get Directory Group

curl -s "https://api.workos.com/directory_groups/<directory-group-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

User Management

List Users

curl -s "https://api.workos.com/user_management/users" --header "Authorization: Bearer $WORKOS_TOKEN"

Filter options via query parameters: email, organization_id, limit (default 10, max 100), after (cursor for pagination).

Get User

curl -s "https://api.workos.com/user_management/users/<user-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Create User

Write to /tmp/workos_user.json:

{
  "email": "<user@example.com>",
  "first_name": "<First>",
  "last_name": "<Last>",
  "email_verified": true
}

curl -s -X POST "https://api.workos.com/user_management/users" --header "Authorization: Bearer $WORKOS_TOKEN" --header "Content-Type: application/json" -d @/tmp/workos_user.json

Update User

Write to /tmp/workos_user_update.json:

{
  "first_name": "<Updated First>",
  "last_name": "<Updated Last>"
}

curl -s -X PUT "https://api.workos.com/user_management/users/<user-id>" --header "Authorization: Bearer $WORKOS_TOKEN" --header "Content-Type: application/json" -d @/tmp/workos_user_update.json

Delete User

curl -s -X DELETE "https://api.workos.com/user_management/users/<user-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Organization Memberships

List Organization Memberships

curl -s "https://api.workos.com/user_management/organization_memberships?organization_id=<organization-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Create Organization Membership

Write to /tmp/workos_membership.json:

{
  "user_id": "<user-id>",
  "organization_id": "<organization-id>"
}

curl -s -X POST "https://api.workos.com/user_management/organization_memberships" --header "Authorization: Bearer $WORKOS_TOKEN" --header "Content-Type: application/json" -d @/tmp/workos_membership.json

Delete Organization Membership

curl -s -X DELETE "https://api.workos.com/user_management/organization_memberships/<membership-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Audit Logs

List Audit Log Events

Write to /tmp/workos_audit_export.json:

{
  "organization_id": "<organization-id>",
  "actions": ["user.signed_in", "user.signed_out"],
  "range_start": "2024-01-01T00:00:00.000Z",
  "range_end": "2024-12-31T23:59:59.999Z"
}

Create an export first:

curl -s -X POST "https://api.workos.com/audit_logs/exports" --header "Authorization: Bearer $WORKOS_TOKEN" --header "Content-Type: application/json" -d @/tmp/workos_audit_export.json

Then poll the export using the returned id until state is ready:

curl -s "https://api.workos.com/audit_logs/exports/<export-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

When state is ready, download the CSV from the url field in the response.

Roles (RBAC)

List Roles

curl -s "https://api.workos.com/roles" --header "Authorization: Bearer $WORKOS_TOKEN"

Get Role

curl -s "https://api.workos.com/roles/<role-id>" --header "Authorization: Bearer $WORKOS_TOKEN"

Pagination

All list endpoints support cursor-based pagination via after and limit parameters:

curl -s "https://api.workos.com/organizations?limit=20&after=<cursor>" --header "Authorization: Bearer $WORKOS_TOKEN"

Response includes list_metadata.after (cursor for the next page, null when on the last page) and list_metadata.before.

Prerequisites

Connect the WorkOS connector at app.vm0.ai/connectors.

Troubleshooting: If requests fail, run zero doctor check-connector --env-name WORKOS_TOKEN or zero doctor check-connector --url https://api.workos.com/organizations --method GET

Guidelines

  1. API key types: Use sk_live_... keys for production and sk_test_... for sandbox/testing environments. The test environment has separate organizations and users.
  2. Pagination: All list endpoints return up to 100 records per page. Use the after cursor from list_metadata.after to retrieve subsequent pages.
  3. Audit Log exports: Audit log data is exported asynchronously — create an export, then poll until state is ready before downloading.
  4. Organization domains: SSO connections and directory sync are scoped to organizations. Always retrieve the organization ID before managing connections or directories.
  5. Rate limits: WorkOS enforces per-environment rate limits. Implement exponential backoff for 429 responses.