WorkOS AuthKit API Reference

Step 1: Fetch Documentation

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

• https://workos.com/docs/reference/authkit
• https://workos.com/docs/reference/authkit/api-keys
• https://workos.com/docs/reference/authkit/api-keys/create-for-organization
• https://workos.com/docs/reference/authkit/api-keys/delete
• https://workos.com/docs/reference/authkit/api-keys/list-for-organization
• https://workos.com/docs/reference/authkit/api-keys/validate
• https://workos.com/docs/reference/authkit/authentication
• https://workos.com/docs/reference/authkit/authentication-errors

Authentication Setup

Set your API key as a bearer token in all requests:

curl -X GET https://api.workos.com/user_management/users \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"

SDK configuration:

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

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

Endpoint Catalog

Authentication Operations

User Management

Organization Membership

Invitations

MFA Operations

Magic Auth

Password Reset

Email Verification

CLI Auth (Device Flow)

Operation Decision Tree

Authentication Flow

• Starting OAuth flow → GET /user_management/authorize → Generate authorization URL
• Handling callback → POST /user_management/authenticate with code → Receive tokens
• Refreshing session → Use refresh token with SDK refreshSession() method
• Logging out → DELETE /user_management/sessions/{session_id}

User CRUD

• Create new user → POST /user_management/users with email, password, firstName, lastName
• Find existing user → GET /user_management/users/{user_id} OR GET /user_management/users?email={email}
• Update user → PUT /user_management/users/{user_id} with fields to change
• Delete user → DELETE /user_management/users/{user_id} (permanent)

Organization Membership

• Add user to org → POST /user_management/organization_memberships with user_id and organization_id
• Remove from org → DELETE /user_management/organization_memberships/{membership_id}
• Soft deactivate → POST /user_management/organization_memberships/{id}/deactivate
• Reactivate → POST /user_management/organization_memberships/{id}/reactivate

Invitations

• Invite new user → POST /user_management/invitations with email and organization_id
• Check invite status → GET /user_management/invitations/{invitation_id}
• Cancel invite → POST /user_management/invitations/{invitation_id}/revoke
• Resend invite → Send new invitation (no dedicated endpoint, create new)

MFA Enrollment

• User enrolls MFA → POST /user_management/authentication_factors with type: totp and totp_issuer
• Challenge at login → POST /user_management/challenges with authentication_factor_id
• Verify challenge → POST /user_management/challenges/{challenge_id}/verify with code

Request/Response Patterns

Create User

curl -X POST https://api.workos.com/user_management/users \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "first_name": "Jane",
    "last_name": "Doe",
    "email_verified": false
  }'

Response:

{
  "object": "user",
  "id": "user_01HXYZ...",
  "email": "user@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "email_verified": false,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Get Authorization URL

curl -X GET "https://api.workos.com/user_management/authorize?client_id=client_123&redirect_uri=https://app.com/callback&response_type=code&provider=authkit" \
  -H "Authorization: Bearer sk_live_..."

Response:

{
  "url": "https://auth.workos.com/sso/authorize?client_id=client_123&..."
}

Authenticate with Code

curl -X POST https://api.workos.com/user_management/authenticate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "client_123",
    "code": "01HXYZ...",
    "code_verifier": "challenge_verifier"
  }'

Response:

{
  "user": {
    "object": "user",
    "id": "user_01HXYZ...",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "email_verified": true
  },
  "organization_id": "org_01HXYZ...",
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "refresh_01HXYZ..."
}

Send Invitation

curl -X POST https://api.workos.com/user_management/invitations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "organization_id": "org_01HXYZ...",
    "expires_in_days": 7
  }'

Response:

{
  "object": "invitation",
  "id": "invitation_01HXYZ...",
  "email": "newuser@example.com",
  "state": "pending",
  "organization_id": "org_01HXYZ...",
  "expires_at": "2024-01-22T10:30:00.000Z",
  "token": "inv_token_abc123...",
  "created_at": "2024-01-15T10:30:00.000Z"
}

Pagination Handling

List endpoints support cursor-based pagination:

curl -X GET "https://api.workos.com/user_management/users?limit=10&after=user_01HXYZ..." \
  -H "Authorization: Bearer sk_live_..."

Response includes list_metadata:

{
  "data": [...],
  "list_metadata": {
    "after": "user_01HXYZ...",
    "before": null
  }
}

To fetch next page, pass after value as query parameter. Continue until after is null.

Error Code Mapping

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Rate Limits

• Default limit: 100 requests/second per API key
• Burst allowance: Up to 200 requests in 10-second window
• Response headers: Check X-RateLimit-Remaining and X-RateLimit-Reset

Retry strategy:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

Runnable Verification Commands

Verify API Key

curl -X GET https://api.workos.com/user_management/users?limit=1 \
  -H "Authorization: Bearer $WORKOS_API_KEY" \
  -H "Content-Type: application/json"

Expected: 200 response with user list (may be empty).

Test User Creation

curl -X POST https://api.workos.com/user_management/users \
  -H "Authorization: Bearer $WORKOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "TestPass123!",
    "first_name": "Test",
    "last_name": "User"
  }'

Expected: 201 response with user object containing id, email, created_at.

Test Authorization URL Generation

curl -X GET "https://api.workos.com/user_management/authorize?client_id=$WORKOS_CLIENT_ID&redirect_uri=https://localhost:3000/callback&response_type=code&provider=authkit" \
  -H "Authorization: Bearer $WORKOS_API_KEY"

Expected: 200 response with url field containing WorkOS hosted auth page.

Test Session Revocation

# First authenticate to get session_id, then:
curl -X DELETE https://api.workos.com/user_management/sessions/session_01HXYZ... \
  -H "Authorization: Bearer $WORKOS_API_KEY"

Expected: 204 No Content response.

SDK Usage Examples

Node.js (JavaScript/TypeScript)

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

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

// Create user
const user = await workos.userManagement.createUser({
  email: 'user@example.com',
  password: 'SecurePass123!',
  firstName: 'Jane',
  lastName: 'Doe',
});

// Get authorization URL
const authorizationUrl = await workos.userManagement.getAuthorizationUrl({
  provider: 'authkit',
  clientId: process.env.WORKOS_CLIENT_ID,
  redirectUri: 'https://app.com/callback',
});

// Authenticate with code
const { user, organizationId } = await workos.userManagement.authenticateWithCode({
  code: req.query.code,
  clientId: process.env.WORKOS_CLIENT_ID,
});

// List users with pagination
const { data: users, listMetadata } = await workos.userManagement.listUsers({
  limit: 10,
  after: 'user_01HXYZ...',
});

Python

from workos import WorkOS

workos = WorkOS(api_key=os.environ['WORKOS_API_KEY'])

# Create user
user = workos.user_management.create_user(
    email='user@example.com',
    password='SecurePass123!',
    first_name='Jane',
    last_name='Doe',
)

# Get authorization URL
authorization_url = workos.user_management.get_authorization_url(
    provider='authkit',
    client_id=os.environ['WORKOS_CLIENT_ID'],
    redirect_uri='https://app.com/callback',
)

# Authenticate with code
auth_response = workos.user_management.authenticate_with_code(
    code=request.args.get('code'),
    client_id=os.environ['WORKOS_CLIENT_ID'],
)

Ruby

require 'workos'

WorkOS.key = ENV['WORKOS_API_KEY']

# Create user
user = WorkOS::UserManagement.create_user(
  email: 'user@example.com',
  password: 'SecurePass123!',
  first_name: 'Jane',
  last_name: 'Doe',
)

# Get authorization URL
authorization_url = WorkOS::UserManagement.authorization_url(
  provider: 'authkit',
  client_id: ENV['WORKOS_CLIENT_ID'],
  redirect_uri: 'https://app.com/callback',
)

# Authenticate with code
auth_response = WorkOS::UserManagement.authenticate_with_code(
  code: params[:code],
  client_id: ENV['WORKOS_CLIENT_ID'],
)

Related Skills

• workos-authkit-base — Core AuthKit integration patterns and session management
• workos-authkit-nextjs — Next.js-specific AuthKit implementation
• workos-authkit-react — React hooks and components for AuthKit
• workos-authkit-react-router — React Router integration
• workos-authkit-vanilla-js — Pure JavaScript AuthKit implementation
• workos-mfa — Multi-factor authentication setup and verification
• workos-magic-link — Passwordless magic link authentication
• workos-sso — Single Sign-On integration patterns
• workos-api-organization — Organization management endpoints
• workos-admin-portal — Self-service admin portal configuration