llms.txt

WorkOS Documentation

WorkOS is the enterprise authentication and identity platform for SaaS companies. AuthKit ships email/password, social login, passkeys, MFA, magic auth, and enterprise SSO from one integration, and is free up to 1M monthly active users. Enterprise APIs include Single Sign-On, SCIM Directory Sync, RBAC, Audit Logs, Radar (bot and fraud protection), Vault, and a no-code Admin Portal — priced per connection with volume discounts. SDKs for Node, Python, Go, Ruby, PHP, Java, and .NET.

This documentation site provides guides, references, and examples for implementing WorkOS features in your applications.

Getting started

Auth: Instructions for how agents can set up a new WorkOS account and start developing with the SDKs.

Pricing

Pricing: WorkOS pricing details for AuthKit, SSO, Directory Sync, Audit Logs, Radar, and more.

Postman

WorkOS Postman collection: Test the WorkOS API with Postman.

On prem deployment

Using WorkOS with On-prem Customers: Best practices for using WorkOS with on-prem customers.

Migrate standalone sso

Migrate from the standalone SSO API: Learn how to migrate your code from an existing WorkOS SSO integration.

Mcp

WorkOS MCP Server: Manage your WorkOS workspace with AI agents. The WorkOS MCP server lets any Model Context Protocol client manage organizations, users, SSO connections, and more.

Glossary

Glossary: Terminology and concepts used in the WorkOS documentation.

Email

Email delivery: Best practices for sending email with WorkOS.

Widgets API

Getting started: GraphQL queries, mutations, and type definitions for the WorkOS Widgets API.
verify-current-email
user
update-profile
send-verification-code
send-email-change
me
Users: Read and update the profile of the user the token was issued for.
confirm-email-change
update-sso-connection
sso-connections
sso-connection
Single Sign-On: Manage the SSO connections of the organization the token was issued for.
delete-sso-connection
create-sso-connection
update-role
roles
role
permissions
Roles and permissions: Define the roles available to an organization, the permissions attached to them, and the permissions a given member effectively holds.
effective-permissions
delete-role
create-role
assign-permission-to-role
Pagination: How to page through list results in the Widgets API using cursors.
update-member-role
revoke-invitation
resend-invitation
remove-member
organizations
organization
organization-memberships
invite-user
Organizations: List the organizations a user belongs to and manage the membership of the organization the token was issued for, including invitations and each member's roles.
Errors: How the Widgets API reports both expected and unexpected failures.
reverify-organization-domain
organization-domains
organization-domain
Domain verification: Add domains to the organization the token was issued for and track the DNS verification of each one.
delete-organization-domain
create-organization-domain
Directory Sync: Read the directory connections of the organization the token was issued for, along with their synced users and groups.
directory-users
directory-groups
directory-connections
directory-connection
set-data-provider-enabled
set-data-provider-configuration
organization-data-providers
Data providers: Browse the data providers configured in the environment, manage which ones the organization can use, and connect or disconnect the authenticated user's own accounts.
delete-data-provider-connection
data-providers
data-provider
data-provider-connections
data-provider-connection
data-provider-authorization-status
create-organization-data-provider-authorization
create-data-provider-connection
create-data-provider-authorization
connect-data-provider-with-client-credentials
Branding: Read the branding for the environment the token was issued for.
branding
Authentication: How to issue and use the short-lived tokens that authorize Widgets API requests.
verify-totp
verify-passkey
update-password
sessions
revoke-session
revoke-all-sessions
remove-mfa-factor
register-passkey
passkeys
Authentication: Inspect the environment's authentication settings and manage the signed-in user's passwords, multi-factor factors, passkeys, and active sessions.
enroll-totp
delete-passkey
create-password
authkit-settings
authentication-settings
Audit logs: Search the audit events of the organization the token was issued for and export them.
create-audit-log-export
audit-log-stream
audit-log-export
audit-events
audit-event
Admin Portal: Hand a user off to Admin Portal for a setup flow that is too involved to reproduce in a widget.
create-admin-portal-link

Widgets

User Sessions Widget: A widget for displaying and managing user sessions in your application.
User Security Widget: A widget for controlling user security settings in your application.
User Profile Widget: A widget for displaying and managing a user's profile in your application.
User Management Widget: A widget for displaying and managing users in your application.
Authorization Tokens: Ensure Widgets have the appropriate permissions in your application.
Quick Start: A step-by-step guide for setting up WorkOS Widgets in your application.
Pipes Widget: A widget for displaying and managing connected accounts with Pipes.
Pipes Admin Widget: A widget for organization admins to manage their organization's Pipes connections — enabling providers, supplying OAuth credentials, and configuring scopes.
Organization Switcher Widget: A widget for switching between organizations in your application.
Localization: Learn how to display Widgets in multiple languages.
WorkOS Widgets: Learn how to integrate WorkOS Widgets in your app.
Directory Sync Widget: A widget for managing Directory Sync connections in the Admin Portal.
Audit Log Streaming Widget: A widget for configuring and monitoring audit log streaming in the Admin Portal.
API Keys Widget: A widget for displaying and managing API keys.
SSO Connection Widget: A widget for setting up SSO connections in the Admin Portal.
Domain Verification Widget: A widget for verifying domains in the Admin Portal.
Theme Customization: Customize the look and feel of WorkOS Widgets using Radix Themes.
Styling: Customize the look and feel of WorkOS Widgets.
CSS Customization: Customize the look and feel of WorkOS Widgets using CSS.

Vault

Quick Start: A step-by-step guide on how to start using Vault to manage encrypted objects.
Key Context: User-managed cardinality for keys within Vault.
Vault: Encrypt, store, and control access to sensitive data.
Bring Your Own Key (BYOK): Allow your customers to use their own encryption keys with WorkOS Vault for enhanced security and compliance.

Single Sign-On

Test SSO: Learn how to test your Single Sign-On integration end-to-end.
Single Logout: Learn how to implement Single Logout with WorkOS
SAML Signing Certificates: Verify the authenticity of SAML responses and requests.
Sign-in Consent: Learn about the sign-in consent screen, an extra layer of protection against login CSRF attacks and phishing attempts.
SAML Security Considerations: Learn about additional SAML features that WorkOS supports.
Redirect URIs: Learn what a redirect URI is and how it relates to Service Provider and Identity Provider initiated login flows.
Login Flows: Learn the differences between SP‑initiated and IdP‑initiated SSO.
Launch Checklist: Make sure you're ready to take your app to production.
Just-In-Time User Provisioning: Learn how to provision users in your app using Just-In-Time user provisioning.
FAQ for IT teams: Answers to common questions from your customer's IT team.
Single Sign-On: Facilitate greater security, easier account management, and accelerated application onboarding and adoption.
Identity Provider Role Assignment: Learn how to map role data from identity providers to roles in your app with SSO.
Example Apps: View sample Single Sign-On apps for each SDK.
Domains: Understand how Organization domains are used with SSO.
IdP Attributes: Configure how identity provider attributes map to SSO Profiles and Directory Users.
Sign-In UX: User experience considerations for Single Sign-On.
SSO Session Lifecycle: Understanding SSO session statuses and their meaning.

Sdks

API Reference

RBAC

Quick Start: Set up roles & permissions to model your authorization requirements. Then use the SDK to make access checks from your application.
Integrating Role-Based Access Control: Utilize Role-Based Access Control across WorkOS products
Role-Based Access Control (RBAC): Assign roles and manage access for users and organizations
IdP Role Assignment: Map identity provider groups to roles to automatically assign roles to users
Custom Roles: Create and manage custom organization-scoped roles
Configuration: Configure roles and permissions

Pipes

Relay: Call third-party APIs on behalf of your users without handling their provider credentials.
Providers: Explore the third-party providers available for Pipes integrations.
Organization-scoped providers: Per-organization customization for a Pipe provider's scopes, credentials, and enablement.
Pipes: Enable your customers to connect their third-party accounts to your application.
Custom providers: Define your own provider in Pipes when the one you need isn't in the WorkOS catalog.
API key providers: Connect providers that authenticate with an API key instead of OAuth.

Migrations

Migrate from Supabase Auth: Learn how to migrate users from Supabase Auth.
Migrate from Stytch: Learn how to migrate users and organizations from Stytch.
Migrate from other services: Learn how to export and import users from your own data store.
Migrate from Firebase: Learn how to migrate users to WorkOS from Firebase.
Migrate from Descope: Learn how to migrate users and organizations from Descope.
Migrate from Clerk: Learn how to migrate users and organizations from Clerk.
Migrate from Better Auth: Learn how to migrate users and organizations from Better Auth.
Migrate from AWS Cognito: Learn how to migrate users to WorkOS from AWS Cognito.
Migrate from Auth0: Learn how to migrate users, organizations, and enterprise connections from Auth0.

Multi-Factor Auth

Multi-Factor Authentication: A composable API for implementing multi-factor authentication.
Example Apps: View sample Multi-Factor Auth apps for each SDK.
Sign-In UX: User experience considerations for MFA sign-in.
Enrollment UX: User experience considerations for MFA enrollment.

Magic Link

Launch Checklist: Make sure you're ready to take your app to production.
Magic Link: The fastest way to securely enable authentication – passwordless sign-in via email in a couple lines of code.
Example Apps: View sample Magic Link apps for each SDK.

Integrations

Xero OAuth: Learn how to set up OAuth with Xero
Workday: Learn about syncing your user list with Workday.
VMware: Learn how to configure a connection to VMware via SAML.
Vercel OAuth: Learn how to set up OAuth with Vercel
Supabase + WorkOS SSO: Learn how to use WorkOS for SSO with your Supabase application.
Supabase + AuthKit: Learn how to use AuthKit with your Supabase application.
Slack OAuth: Learn how to set up OAuth with Slack
SimpleSAMLphp: Learn how to configure a SimpleSAMLphp connection.
Shibboleth Unsolicited SAML: Learn how to configure a Shibboleth Unsolicited connection via SAML.
Shibboleth Generic SAML: Learn how to configure a Shibboleth Generic connection via SAML.
SFTP: Learn about syncing users with an SFTP connection
SCIM: Learn about syncing users with a custom SCIM provider
SAML: Learn how to configure a new custom SAML connection
Salesforce SAML: Learn how to configure a connection to Salesforce via SAML.
Salesforce OAuth: Learn how to set up OAuth with Salesforce.
SailPoint SCIM: Learn about syncing users with SailPoint SCIM
Rippling SCIM: Learn about syncing your user list with Rippling SCIM v2.0.
Rippling SAML: Learn how to configure a connection to Rippling via SAML.
React Native Expo: Learn how to integrate WorkOS SSO into a React Native Expo app.
PingOne SAML: Learn how to configure a connection to PingOne via SAML.
PingFederate SCIM: Learn about syncing your user list with PingFederate SCIM.
PingFederate SAML: Learn how to configure a connection to PingFederate via SAML.
Oracle SAML: Learn how to configure a connection to Oracle via SAML.
OneLogin SCIM: Learn about syncing your user list with OneLogin SCIM.
OneLogin SAML: Learn how to configure a connection to OneLogin via SAML.
Okta SCIM: Learn about syncing your user list with Okta SCIM.
Okta SAML: Learn how to configure a connection to Okta via SAML.
Okta OIDC: Learn how to configure a connection to Okta via OIDC.
OpenID Connect: Learn how to configure a new generic OIDC connection
NextAuth.js: Create a Next.js application with WorkOS SSO and NextAuth.js.
NetIQ: Learn how to configure a connection to NetIQ via SAML.
miniOrange: Learn how to configure a connection to miniOrange via SAML.
Microsoft OAuth: Learn how to set up OAuth with Microsoft
Microsoft AD FS SAML: Configure a connection to Microsoft Active Directory Federation Services.
Login.gov OpenID Connect: Learn how to configure a connection to Login.gov via OIDC.
LinkedIn OAuth: Learn how to set up OAuth with LinkedIn
LastPass: Learn how to configure a connection to LastPass via SAML.
Keycloak: Learn how to configure a connection to Keycloak via SAML.
JumpCloud SCIM: Learn about syncing your user list with JumpCloud SCIM.
JumpCloud SAML: Learn how to configure a connection to JumpCloud via SAML.
Intuit OAuth: Learn how to set up OAuth with Intuit
HiBob: Learn about syncing your user list with HiBob.
Google SAML: Learn how to configure a connection to Google Workspace via SAML.
Google OIDC: Learn how to configure a connection to Google via OIDC.
Google OAuth: Learn how to set up OAuth with Google Workspace
Google Directory Sync: Learn about syncing your user list with Google Workspace.
GitLab OAuth: Learn how to set up OAuth with GitLab
GitHub OAuth: Learn how to set up OAuth with GitHub
Fourth: Learn about syncing your user list with Fourth.
Firebase: Add Single Sign-On to your Firebase application with WorkOS.
Entra ID SCIM (formerly Azure AD): Learn about syncing your user list with Entra ID SCIM.
Entra ID SAML (formerly Azure AD): Learn how to configure a connection to Entra ID via SAML.
Entra ID OIDC (formerly Azure AD): Learn how to configure a connection to Entra ID via OIDC.
Duo: Learn how to configure a connection to Duo via SAML.
CyberArk SCIM: Learn about syncing your user list with CyberArk SCIM.
CyberArk SAML: Learn how to configure a connection to CyberArk via SAML.
Cloudflare: Learn how to configure a connection to Cloudflare via SAML.
Clever OIDC: Learn how to configure a connection to Clever via OIDC.
ClassLink: Learn how to configure a connection to ClassLink via SAML.
Cezanne HR: Learn about syncing your user list with Cezanne HR.
CAS SAML: Learn how to configure a connection to CAS via SAML.
Bubble Plugin: Add WorkOS features to your Bubble application.
Breathe HR: Learn about syncing your user list with Breathe HR.
BambooHR: Learn about syncing your user list with BambooHR.
AWS Cognito: Learn how to use WorkOS with your existing AWS Cognito applications.
Auth0: Learn how to configure a connection to Auth0 via SAML.
Auth0 Enterprise Connection: Learn how to use WorkOS with your existing Auth0 applications.
Apple: Learn how to set up "Sign in with Apple"
ADP OpenID Connect: Learn how to configure a connection to ADP via OIDC.
Access People HR: Learn about syncing your user list with Access People HR.

FGA

Standalone Integration: Use FGA with your own authentication system by managing users, organizations, and memberships via API.
Roles and Permissions: Define what users can do within specific resource types.
Resources: Represent your application's entities in the FGA hierarchy.
Resource Types: Define the schema of your application's resource hierarchy in the WorkOS Dashboard.
Resource Discovery: Find which resources a user can access, or who has access to a resource.
Quick Start: Build a complete authorization model from resource types to access checks in minutes.
Share Button: Build a share dialog that lists current members of a resource and grants or revokes access.
Multi-level Inheritance: Model authorization for nested resources and permission-gated UI components.
High-Cardinality Data: Use FGA to authorize high-cardinality data like documents, files, and messages without syncing them as resources.
Basic App: Model authorization for a project management app with list and detail pages.
Protecting API Endpoints: Use the check endpoint to protect every CRUD operation in your REST API.
Migrate from SpiceDB: Map your SpiceDB schema to WorkOS FGA resource types, roles, and permissions.
Migrate from Oso Cloud: Map your Oso Cloud Polar policies to WorkOS FGA resource types, roles, and permissions.
Migrate from OpenFGA: Map your OpenFGA authorization model to WorkOS FGA resource types, roles, and permissions.
Fine-Grained Authorization (FGA): Scalable fine-grained authorization built for B2B SaaS.
IdP Role Assignment: Map identity provider groups to organization-scoped roles while preserving resource-scoped access.
High-Cardinality Entities: Learn when to use FGA for authorization and when to handle access control in your application.
AuthKit Integration: Use FGA with AuthKit for role-aware sessions and seamless authorization.
Role Assignments: Grant users and groups access to specific resources through role assignments.
Access Checks: Ask whether a user can perform an action on a resource.

Feature Flags

Slack Notifications: Get notifications about feature flag changes in your Slack workspace.
SDK Integration: Choose between the feature_flags access token claim and the Node runtime client.
Node runtime client: Evaluate feature flags in a server-side Node application with the WorkOS runtime client.
Feature Flags: Manage rollout of new features for specific users and organizations with Feature Flags.
Custom Targets: Target a feature flag at resources in your own application, such as workspaces, accounts, or environments, instead of only WorkOS users and organizations.
Access token claim: Read the feature_flags claim from a user's access token on any platform with an AuthKit SDK.

Events

Events: Respond to activity that occurs within WorkOS and third-party providers.
Stream events to Datadog: Stream and analyze WorkOS activity in Datadog.
Sync data with webhooks: A step-by-step guide on how to start syncing data using webhooks.
Data syncing: Keep your app in sync with WorkOS.
Sync data using the events API: A step-by-step guide on how to start syncing data using the API.
Data reconciliation: Keep your app in sync with WorkOS.

Domain Verification

Domain Verification: Self-serve domain verification
API: Programmatic domain verification

Directory Sync

Understanding the Events Lifecycle: Understand the lifecycle of the events that occur in Directory Sync.
Quick Start: Set up a directory, install the SDK, and integrate Directory Sync.
Directory Sync: Build frictionless onboarding for organizations with real‑time user provisioning and deprovisioning.
Identity Provider Role Assignment: Learn how to map role data from identity providers to roles in your app with Directory Sync.
Handle Inactive Users: Learn why inactive users are deleted from directories by default and how to configure this behavior.
Example Apps: View sample Directory Sync apps for each SDK.
Unique Emails: Learn why directory user emails must be unique among active users, and how to avoid conflicts.
User Attributes: Configure how attributes map from directory providers to Directory Users.

Deprecations

Migrate from raw_attributes: How to migrate from raw_attributes and legacy standard attributes to custom attributes.

Dashboard

Team activity: Review an audit trail of activity across your WorkOS team.
Team settings: Manage your team's details in the WorkOS dashboard, or delete your team entirely.
Members and roles: Invite team members to the WorkOS dashboard, manage invitations, and assign roles.
Dashboard: Manage your team, members, authentication, and billing.
Billing: Manage your payment method and billing email, view invoices, and track usage in the WorkOS dashboard.
Team authentication: Require multi-factor authentication, set up Single Sign-On, and provision dashboard accounts from your identity provider.

Custom Domains

Custom Domains: Configure your integration to match your brand identity.
Email Domain: Guidance on configuring a custom domain for emails.
AuthKit Domain: Guidance on configuring a custom domain for AuthKit.
Authentication API Domain: Guidance on configuring a custom domain for the Authentication API.
Admin Portal Domain: Guidance on configuring a custom domains for the Admin Portal.

AuthKit

Waitlist: Review and approve signup requests before granting access to your application.
Users and Organizations: Flexible application modeling with user and membership features.
Testing: Run the WorkOS API locally with the emulator and learn what to cover when testing your AuthKit integration — sign-in flows, sessions, webhooks, and failure handling.
Single Sign-On: Facilitate greater security, easier account management, and accelerated application onboarding and adoption.
SSO with contractors: Enforcing organization SSO access with external contractors.
Social Login: Quickly and easily integrate with social OAuth providers.
Sessions: Learn more about integrating sessions.
Session resilience: Understand refresh token rotation, the replay grace period, and how to handle transient failures without signing users out.
Roles and Permissions: Manage and assign roles and permissions to users.
AuthKit: Easy to use authentication platform designed to provide a flexible, secure, and fast integration.
Reauthentication: Require a fresh sign-in for sensitive actions.
AuthKit: Easy to use authentication platform designed to provide a flexible, secure, and fast integration.
Radar: Protecting against bots, fraud and abuse.
Radar Integration Guide: Integrate Radar fraud and bot detection with the User Management APIs or Standalone Radar API.
Projects: Group related environments under a project, and learn when to use projects, environments, and applications.
AuthKit for Platforms: Provision AuthKit for the apps your users build on your platform, so every new app ships with working authentication.
Pipes: Enable your customers to connect their third-party accounts to your application.
Passkeys: Configuring passkey authentication and enrollment.
AuthKit: Easy to use authentication APIs designed to provide a flexible, secure, and fast integration.
Organization Authentication Policies: Customize available authentication methods for each organization.
AuthKit: Easy to use authentication platform designed to provide a flexible, secure, and fast integration.
Modeling Your App: Learn how to architect your WorkOS integration
Migrating to AuthKit: Guidance on moving your existing users to WorkOS.
Multi-Factor Authentication: Add an additional layer of security to your application.
Metadata and External IDs: Store additional information about users and organizations.
Model Context Protocol: How to use AuthKit as the OAuth authorization server for your MCP server.
Magic Auth: Maximize user experience and security with passwordless authentication.
Get started with AuthKit: Set up AuthKit in your app using either the AI Installer & CLI or a manual framework-specific guide.
JWT Templates: Customize the claims in your application's access tokens.
Just-in-time Provisioning: Automatically provision users and memberships with JIT provisioning.
Invite-only signup: Modeling an invite-only application without a public signup page.
Invitations: Easily add users to your application or as members of an organization.
Get started with AuthKit: Set up AuthKit in your app using either the AI Installer & CLI or a manual framework-specific guide.
Impersonation: Learn how to sign into your application as one of your users.
Identity Linking: Automatic deduplication of user credentials across identity providers.
Hosted UI: Customizable sign-in UI that abstracts away all of the complexity associated with building secure authentication flows.
Groups: Organize organization members into groups for easier management.
Group Role Assignments: Assign roles to groups so all members automatically inherit the role and its permissions.
Example apps: View sample AuthKit apps.
Staging vs. production environments: Understand the differences between staging and production environments, when to use each, and how to go live.
Email Verification: Learn more about the email verification process.
Email + Password: Configuring email and password authentication and requirements.
Email Changes: How email address changes from identity providers propagate to AuthKit users.
Domain Verification: Verify organization domains for secure authentication and provisioning.
Directory Provisioning: Manage users and organization memberships via directory sync providers.
Custom Emails: Learn how to send your own emails for user lifecycle events.
Custom Email Providers: Learn how to send emails through your own email service provider.
Connect: Enable other applications to access your users and their identities.
AI Installer & CLI: Integrate AuthKit with one command, manage resources, provision environments, and equip your coding agents — all from the WorkOS CLI.
CLI Auth: Quickly add authentication to your command-line application.
Branding: Customize AuthKit to fit natively with your app's unique design.
Applications: Manage authentication across every surface your product runs on with a shared identity layer.
API Keys: Provide secure, self-service API key management to your customers.
API Gateway: Put your API behind a WorkOS-managed gateway that authenticates requests and forwards a signed identity assertion to your origin.
Agent Registration: How agents obtain identity and credentials from an AuthKit-powered service.
Agent Auth: Define reusable agent configurations and mint scoped, short-lived tokens for AI agents acting in your app.
Actions: Customize authentication flows with your own logic.
AuthKit: Easy to use authentication platform designed to provide a flexible, secure, and fast integration.
AuthKit: Easy to use authentication platform designed to provide a flexible, secure, and fast integration.
AuthKit: Easy to use authentication platform designed to provide a flexible, secure, and fast integration.
Provision your first environment: Walk through provisioning AuthKit for an app on your platform, from platform credentials to a running sign-in flow.
Standalone Connect: Integrate Connect's OAuth API with your existing authentication stack.
OAuth Applications: Integrate OAuth applications with WorkOS Connect for web and mobile authentication.
M2M Applications: Implement machine-to-machine authentication with WorkOS Connect.
Stripe: Connect your WorkOS account to Stripe to automatically provision access tokens with entitlements and sync organization seat counts.
Segment: Send AuthKit events to your Segment destinations.
Google Analytics: Track user activity on AuthKit pages in Google Analytics.

Audit Logs

Metadata Schema: Define strict JSON Schema for validating event metadata.
Log Streams: Stream Audit Log Events to your customers' SIEM providers.
Audit Logs: Ingest and export Audit Log Events from your application.
Exporting Events: Export Audit Log Events through the WorkOS Dashboard and API.
Editing Events: Modify existing event configuration with backwards compatibility.
Admin Portal: View Audit Log events for an organization in the WorkOS Admin Portal.

Admin Portal

Bearer token rotation: Create and revoke SCIM bearer tokens from the WorkOS Dashboard or Admin Portal.
Admin Portal: A first-class Single Sign-On and Directory Sync onboarding experience for IT contacts.
Example Apps: View sample Admin Portal apps for each SDK.
Custom Branding: Use your own logo and colors in the Admin Portal.