WorkOS Organizations API Reference

Step 1: Fetch Documentation

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

• https://workos.com/docs/reference/organization
• https://workos.com/docs/reference/organization/create
• https://workos.com/docs/reference/organization/delete
• https://workos.com/docs/reference/organization/get
• https://workos.com/docs/reference/organization/get-by-external-id
• https://workos.com/docs/reference/organization/list
• https://workos.com/docs/reference/organization/update

Endpoint Catalog

Authentication Setup

All requests require the Authorization header with your API key:

Authorization: Bearer sk_live_1234567890abcdef

Set your API key as an environment variable:

export WORKOS_API_KEY=sk_live_1234567890abcdef

Operation Decision Tree

Creating a new tenant?

• Use POST /organizations with name (required) and optional domains, external_id, metadata

Looking up an organization?

• Have WorkOS org ID? → Use GET /organizations/{id}
• Have your system’s ID? → Use GET /organizations/external_id/{external_id}
• Need to browse/search? → Use GET /organizations with filters

Updating organization details?

• Use PUT /organizations/{id} with fields to change (name, domains, metadata)
• Cannot change external_id after creation

Removing an organization?

• Use DELETE /organizations/{id} (soft delete — SSO/DSYNC connections remain retrievable)

Request/Response Patterns

Create Organization

Request:

curl -X POST https://api.workos.com/organizations \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domains": ["acme.com", "acme.co"],
    "external_id": "acme_12345",
    "metadata": {
      "plan": "enterprise",
      "region": "us-west"
    }
  }'

Response (201):

{
  "object": "organization",
  "id": "org_01H1QZ...",
  "name": "Acme Corp",
  "domains": [
    {
      "object": "organization_domain",
      "id": "org_domain_01H1QZ...",
      "domain": "acme.com"
    }
  ],
  "external_id": "acme_12345",
  "metadata": {
    "plan": "enterprise",
    "region": "us-west"
  },
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Get Organization by ID

Request:

curl -X GET https://api.workos.com/organizations/org_01H1QZ... \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response (200): Same structure as create response

Get Organization by External ID

Request:

curl -X GET https://api.workos.com/organizations/external_id/acme_12345 \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response (200): Same structure as create response

List Organizations (Paginated)

Request:

curl -X GET "https://api.workos.com/organizations?limit=10&before=org_01H1QZ..." \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response (200):

{
  "object": "list",
  "data": [
    {
      "object": "organization",
      "id": "org_01H1QZ...",
      "name": "Acme Corp",
      ...
    }
  ],
  "list_metadata": {
    "before": "org_01H1QZ...",
    "after": "org_01H1QY..."
  }
}

Pagination pattern: Use before cursor to page backward, after cursor to page forward. Default limit is 10, max is 100.

Update Organization

Request:

curl -X PUT https://api.workos.com/organizations/org_01H1QZ... \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "domains": ["acme.com"],
    "metadata": {
      "plan": "premium"
    }
  }'

Response (200): Updated organization object

Delete Organization

Request:

curl -X DELETE https://api.workos.com/organizations/org_01H1QZ... \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response (204): No content (successful deletion)

Error Code Mapping

SDK Usage Patterns

Node.js SDK

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

// Create organization
const org = await workos.organizations.createOrganization({
  name: 'Acme Corp',
  domains: ['acme.com'],
  externalId: 'acme_12345',
  metadata: { plan: 'enterprise' }
});

// Get by ID
const orgById = await workos.organizations.getOrganization('org_01H1QZ...');

// Get by external ID
const orgByExternalId = await workos.organizations.getOrganizationByExternalId('acme_12345');

// List with pagination
const orgs = await workos.organizations.listOrganizations({
  limit: 10,
  before: 'org_01H1QZ...'
});

// Update
const updated = await workos.organizations.updateOrganization('org_01H1QZ...', {
  name: 'Acme Corporation',
  domains: ['acme.com']
});

// Delete
await workos.organizations.deleteOrganization('org_01H1QZ...');

Python SDK

from workos import WorkOSClient

workos = WorkOSClient(api_key=os.getenv('WORKOS_API_KEY'))

# Create organization
org = workos.organizations.create_organization(
    name='Acme Corp',
    domains=['acme.com'],
    external_id='acme_12345',
    metadata={'plan': 'enterprise'}
)

# Get by ID
org_by_id = workos.organizations.get_organization('org_01H1QZ...')

# Get by external ID
org_by_external_id = workos.organizations.get_organization_by_external_id('acme_12345')

# List with pagination
orgs = workos.organizations.list_organizations(
    limit=10,
    before='org_01H1QZ...'
)

# Update
updated = workos.organizations.update_organization(
    'org_01H1QZ...',
    name='Acme Corporation',
    domains=['acme.com']
)

# Delete
workos.organizations.delete_organization('org_01H1QZ...')

Rate Limiting

• Default limit: 100 requests per second per API key
• Retry strategy: Implement exponential backoff starting at 1s, doubling up to 32s max
• Header hints: Check X-RateLimit-Remaining and X-RateLimit-Reset headers

Verification Commands

1. Test API key authentication

curl -X GET "https://api.workos.com/organizations?limit=1" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -w "\nHTTP Status: %{http_code}\n"

Expected: HTTP 200 with organization list (or empty array)

2. Create test organization

ORG_RESPONSE=$(curl -s -X POST https://api.workos.com/organizations \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Org",
    "external_id": "test_'$(date +%s)'"
  }')

echo $ORG_RESPONSE | jq '.id'

Expected: Returns organization ID starting with org_

3. Retrieve by external ID

curl -X GET https://api.workos.com/organizations/external_id/test_1234567890 \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -w "\nHTTP Status: %{http_code}\n"

Expected: HTTP 200 if exists, HTTP 404 if not

4. Test pagination

curl -X GET "https://api.workos.com/organizations?limit=2" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  | jq '.list_metadata'

Expected: Returns before and after cursors if >2 orgs exist

5. Test error handling (invalid domain)

curl -X POST https://api.workos.com/organizations \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bad Domain Test",
    "domains": ["not a valid domain!"]
  }' \
  -w "\nHTTP Status: %{http_code}\n"

Expected: HTTP 422 with unprocessable_entity error

Common Integration Patterns

Pattern 1: Sync external CRM to WorkOS

// On customer creation in your system
const customer = await createCustomerInCRM({ name: 'Acme Corp' });

const org = await workos.organizations.createOrganization({
  name: customer.name,
  externalId: customer.id, // Link to your system
  metadata: {
    crmId: customer.id,
    salesforceId: customer.salesforce_id
  }
});

Pattern 2: Lookup organization from webhook

// In webhook handler
app.post('/webhooks/workos', async (req, res) => {
  const event = req.body;
  
  if (event.data.organization_id) {
    const org = await workos.organizations.getOrganization(
      event.data.organization_id
    );
    
    // Use org.external_id to query your database
    const customer = await db.customers.findOne({ id: org.external_id });
  }
});

Pattern 3: Batch update organization metadata

const orgs = await workos.organizations.listOrganizations({ limit: 100 });

for (const org of orgs.data) {
  const customer = await getCustomerFromCRM(org.external_id);
  
  await workos.organizations.updateOrganization(org.id, {
    metadata: {
      ...org.metadata,
      plan: customer.subscription_tier,
      mrr: customer.monthly_revenue
    }
  });
}

Troubleshooting

“Organization not found” after creation

Cause: Using wrong ID format or deleted organization Fix: Verify you’re using the id field (not external_id) from create response

Duplicate external_id error

Cause: Attempting to create org with external_id that already exists Fix: Query by external_id first; if exists, use update instead of create

Domains not appearing in org object

Cause: Invalid domain format (e.g., including protocol or path) Fix: Use bare hostnames: "acme.com" not "https://acme.com" or "acme.com/path"

Pagination not returning all results

Cause: Not following cursor-based pagination Fix: Use after cursor from list_metadata to fetch next page until cursor is null

Related Skills

• workos-api-sso — Configure SSO connections for organizations
• workos-api-directory-sync — Set up Directory Sync for organization user provisioning
• workos-api-admin-portal — Generate Admin Portal links for organization self-service
• workos-domain-verification — Verify organization domain ownership
• workos-api-events — Subscribe to organization lifecycle events