WorkOS SSO API Reference

Step 1: Fetch Documentation

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

• https://workos.com/docs/reference/sso
• https://workos.com/docs/reference/sso/connection
• https://workos.com/docs/reference/sso/connection/delete
• https://workos.com/docs/reference/sso/connection/get
• https://workos.com/docs/reference/sso/connection/list
• https://workos.com/docs/reference/sso/get-authorization-url
• https://workos.com/docs/reference/sso/get-authorization-url/error-codes
• https://workos.com/docs/reference/sso/get-authorization-url/redirect-uri

Authentication Setup

All API requests require authentication via Bearer token:

Authorization: Bearer sk_live_1234567890

Set your API key as an environment variable:

export WORKOS_API_KEY="sk_live_1234567890"
export WORKOS_CLIENT_ID="client_1234567890"

Endpoint Catalog

Authorization Endpoints

Connection Management

Profile & Logout

Operation Decision Tree

Task: Initiate SSO login → Use GET /sso/authorize with provider, connection_id, or organization_id → Redirect user to returned authorization URL

Task: Complete SSO login → User returns to redirect URI with code parameter → Use POST /sso/token with the code to exchange for profile

Task: List all connections for an organization → Use GET /connections?organization_id={org_id}

Task: Get details of a specific connection → Use GET /connections/{connection_id}

Task: Remove an SSO connection → Use DELETE /connections/{connection_id}

Task: Get user profile from access token → Use POST /sso/profile with the access token

Task: Log out a user → Use GET /sso/logout with session_id to get logout URL

Request/Response Patterns

GET /sso/authorize – Initiate SSO

Request:

curl "https://api.workos.com/sso/authorize?client_id=${WORKOS_CLIENT_ID}&redirect_uri=https://yourapp.com/callback&response_type=code&provider=GoogleOAuth" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response:

{
  "link": "https://auth.workos.com/sso/authorize?..."
}

Redirect the user to the link URL.

POST /sso/token – Exchange Code for Profile

Request:

curl -X POST "https://api.workos.com/sso/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -d "client_id=${WORKOS_CLIENT_ID}" \
  -d "client_secret=${WORKOS_API_KEY}" \
  -d "code=01HQRS5FJMJXKPQTGBW6S1K9NN" \
  -d "grant_type=authorization_code"

Response:

{
  "access_token": "01HQRS5H...",
  "profile": {
    "id": "prof_01HQRS5H...",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "connection_id": "conn_01HQRS5H...",
    "connection_type": "GoogleOAuth",
    "organization_id": "org_01HQRS5H...",
    "idp_id": "12345",
    "raw_attributes": {}
  }
}

GET /connections – List Connections

Request:

curl "https://api.workos.com/connections?organization_id=org_01HQRS5H..." \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response:

{
  "data": [
    {
      "id": "conn_01HQRS5H...",
      "name": "Acme Corp SAML",
      "connection_type": "SAML",
      "state": "active",
      "organization_id": "org_01HQRS5H..."
    }
  ],
  "list_metadata": {
    "after": null,
    "before": "conn_01HQRS5H..."
  }
}

GET /connections/{id} – Get Connection

Request:

curl "https://api.workos.com/connections/conn_01HQRS5H..." \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response:

{
  "id": "conn_01HQRS5H...",
  "name": "Acme Corp SAML",
  "connection_type": "SAML",
  "state": "active",
  "organization_id": "org_01HQRS5H...",
  "domains": [
    {
      "domain": "acme.com",
      "id": "domain_01HQRS5H..."
    }
  ]
}

DELETE /connections/{id} – Delete Connection

Request:

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

Response:

204 No Content

POST /sso/profile – Get Profile from Token

Request:

curl -X POST "https://api.workos.com/sso/profile" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" \
  -d '{"access_token": "01HQRS5H..."}'

Response:

{
  "profile": {
    "id": "prof_01HQRS5H...",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "connection_id": "conn_01HQRS5H...",
    "connection_type": "GoogleOAuth",
    "organization_id": "org_01HQRS5H..."
  }
}

Error Code Mapping

GET /sso/authorize Errors

POST /sso/token Errors

Connection Management Errors

Pagination Handling

List endpoints (GET /connections) use cursor-based pagination:

Request with cursor:

curl "https://api.workos.com/connections?after=conn_01HQRS5H...&limit=10" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Response includes pagination metadata:

{
  "data": [...],
  "list_metadata": {
    "after": "conn_01HQRS6...",
    "before": "conn_01HQRS5H..."
  }
}

Use after cursor for next page, before for previous page. Default limit is 10, max is 100.

Runnable Verification

Test 1: List Connections

curl "https://api.workos.com/connections?limit=5" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Expected: JSON array of connections with id, name, connection_type, state.

Test 2: Get Authorization URL

curl "https://api.workos.com/sso/authorize?client_id=${WORKOS_CLIENT_ID}&redirect_uri=http://localhost:3000/callback&response_type=code&provider=GoogleOAuth" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Expected: JSON with link field containing authorization URL.

Test 3: Get Connection Details

# First, get a connection ID from the list
CONNECTION_ID=$(curl -s "https://api.workos.com/connections?limit=1" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}" | jq -r '.data[0].id')

# Then fetch its details
curl "https://api.workos.com/connections/${CONNECTION_ID}" \
  -H "Authorization: Bearer ${WORKOS_API_KEY}"

Expected: JSON with full connection details including domains array.

Rate Limit Guidance

WorkOS SSO API has a rate limit of 600 requests per minute per API key.

Rate limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1640000000

When rate limited (status 429):

1. Parse Retry-After header (seconds until reset)
2. Implement exponential backoff: 1s, 2s, 4s, 8s
3. Max 5 retries before failing

Prevention strategies:

• Cache connection details (they rarely change)
• Use webhooks for profile updates instead of polling
• Batch connection lookups where possible

Related Skills

• workos-sso — Feature overview and integration patterns for SSO
• workos-api-organization — Manage organizations that own SSO connections
• workos-admin-portal — Allow customers to self-configure SSO connections
• workos-domain-verification — Verify domains before enabling SSO for them