WorkOS Authentication: Methods, Setup, and Security (2026)

Authentication overview

WorkOS primarily facilitates enterprise-grade authentication and user management for B2B SaaS applications. Its authentication model is designed to allow developers to integrate complex features like Single Sign-On (SSO) and Directory Sync without managing the underlying identity provider complexities. For server-side interactions with the WorkOS API, authentication is managed through API keys. For end-user authentication, WorkOS acts as an intermediary, supporting various protocols to connect applications with enterprise identity providers (IdPs) or provide its own hosted authentication flows.

The platform's focus is on abstracting the intricacies of protocols such as Security Assertion Markup Language (SAML) and OpenID Connect (OIDC) for SSO, and System for Cross-domain Identity Management (SCIM) for directory synchronization. This abstraction allows developers to implement these features with a minimal number of API calls or SDK integrations. WorkOS also offers a hosted login experience through AuthKit, which handles the user interface and redirects for various authentication methods, including Magic Link, thereby reducing development overhead for user-facing authentication flows.

Supported authentication methods

WorkOS supports several authentication methods, catering to both API interactions and end-user identity management within enterprise environments. The choice of method depends on the specific use case, whether it's an application communicating with WorkOS or an end-user authenticating into a SaaS product. For programmatic access to the WorkOS API, a server-side API key is the standard method.

API Key Authentication

API Key authentication is used for all server-to-server communication with the WorkOS API. When making requests, developers include their API Key in the Authorization header as a Bearer token. This key grants access to your WorkOS resources and operations, such as creating SSO connections, managing users and groups via Directory Sync, or configuring audit logs. WorkOS provides separate API keys for development and production environments, following security best practices to prevent unauthorized access to live data. These keys are typically generated from the WorkOS Dashboard.

Single Sign-On (SSO)

WorkOS supports enterprise SSO through prominent protocols:

• SAML (Security Assertion Markup Language): This XML-based standard enables web browsers to request and obtain security assertions from an IdP and transfer them to a service provider (SP), such as a SaaS application integrated with WorkOS. SAML is widely used for enterprise SSO, allowing employees to access multiple applications with a single set of credentials. WorkOS handles the complex SAML handshake with various IdPs like Okta, Azure AD, and Google Workspace. The IETF's documentation on SAML 2.0 Profile for OAuth 2.0 Client Authentication provides additional context on SAML use cases.
• OIDC (OpenID Connect): Built on top of the OAuth 2.0 framework, OIDC is a simpler identity layer that allows clients to verify the identity of the end-user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user. WorkOS provides OIDC support for modern applications that prefer JSON Web Tokens (JWTs) for identity assertions. OAuth.net offers a comprehensive overview of OAuth 2.0 grant types which are foundational to OIDC.

Magic Link

Magic Link authentication provides a passwordless login experience. Users receive a unique, time-limited link via email. Clicking this link authenticates them directly into the application without needing a password. WorkOS offers Magic Link as part of its AuthKit, simplifying its implementation and enhancing user convenience, particularly for consumer-facing or PLG applications that seek reduced friction during onboarding and login.

Directory Sync (SCIM)

While not an authentication method for users to log in, SCIM (System for Cross-domain Identity Management) is crucial for managing user and group identities across different systems. WorkOS uses SCIM to synchronize user and group data from enterprise directories (like Okta, Azure AD, or Google Workspace) to your application. This ensures that user provisioning, de-provisioning, and profile updates are automatically reflected, thereby enhancing security and administrative efficiency. The SCIM 2.0 Core Schema defines the fundamental attributes for users and groups.

Getting your credentials

To begin using WorkOS for authentication, you need to obtain API keys and configure your application within the WorkOS Dashboard. These credentials are vital for securely interacting with the WorkOS API and enabling enterprise features.

WorkOS API Key

1. Sign Up/Log In: Navigate to the WorkOS documentation and sign up for an account or log in to your existing WorkOS Dashboard.
2. Create a Project: Within the Dashboard, create a new project or select an existing one. Each project will have its own set of API keys.
3. Access API Keys: Go to the "Configuration" or "API Keys" section of your project. You will find different API keys for your development and production environments. WorkOS typically provides a "Secret Key" for server-side operations and potentially "Client IDs" for client-side interactions depending on the product (e.g., AuthKit).
4. Store Securely: Copy your Secret Key and store it in a secure location, such as environment variables, a secrets manager, or a .env file (for development). Never hardcode API keys directly into your application's source code or expose them in client-side code.

Configuring SSO and AuthKit

For SSO (SAML/OIDC) and AuthKit, additional configuration steps are required:

1. Create SSO Connection (SAML/OIDC): In the WorkOS Dashboard, navigate to the "SSO" section. You can create a new SSO connection, specifying whether it's for SAML or OIDC. WorkOS provides an Admin Portal that you can share with your enterprise customers, allowing them to self-configure their identity provider details (e.g., IdP metadata XML for SAML).
2. Configure AuthKit: If using AuthKit for hosted login, you'll configure its appearance and enabled authentication methods (e.g., Magic Link, SSO) within the WorkOS Dashboard. You will then integrate the AuthKit flow into your application, often by redirecting users to the WorkOS-hosted login page.
3. Integrate SDKs: WorkOS provides SDKs for various languages (Node, Python, Ruby, PHP, Go, Java, .NET) to simplify integration. These SDKs help manage the authentication flow, handle redirects, and retrieve user profiles after successful authentication.

Authenticated request example

Authenticating with the WorkOS API typically involves including your Secret API Key in the Authorization header of your HTTP requests. The following example demonstrates how to create an SSO connection using the WorkOS Node.js SDK and a direct cURL request.

Using the Node.js SDK

const WorkOS = require('@workos-inc/node').default;

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

async function createSsoConnection() {
  try {
    const connection = await workos.sso.createConnection({
      organizationId: 'org_01E2NRS3M4Z2M4F2K4S2A2B2C',
      connectionType: 'SAML',
      name: 'Example SAML Connection',
      // ... other connection parameters
    });
    console.log('SSO Connection created:', connection);
  } catch (error) {
    console.error('Error creating SSO Connection:', error);
  }
}

createSsoConnection();

Direct HTTP Request (cURL)

This cURL example demonstrates how to retrieve a list of existing SSO connections from the WorkOS API, authenticating with a Secret Key.

curl -X GET \
  'https://api.workos.com/sso/connections' \
  -H 'Authorization: Bearer sk_prod_YOUR_SECRET_API_KEY' \
  -H 'Content-Type: application/json'

Replace sk_prod_YOUR_SECRET_API_KEY with your actual WorkOS Secret API Key. For more detailed API endpoints and request bodies, consult the WorkOS API Reference.

Security best practices

Adhering to security best practices when integrating with WorkOS ensures the confidentiality, integrity, and availability of your application and user data. WorkOS itself is compliant with standards like SOC 2 Type II and ISO 27001, but developers must ensure secure usage on their end.

• Protect API Keys: Your WorkOS Secret API Key grants significant access to your account.
• Environment Variables: Store API keys as environment variables rather than hardcoding them. This prevents them from being committed to version control systems.
• Secrets Management: For production environments, use a dedicated secrets management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault) to store and inject API keys securely.
• Access Control: Restrict access to API keys to only the necessary personnel and systems. Rotate keys regularly.
• Use HTTPS: Always interact with the WorkOS API over HTTPS to ensure that all data in transit is encrypted. WorkOS endpoints enforce HTTPS by default.
• Validate Callbacks and Webhooks: When WorkOS sends data back to your application (e.g., post-authentication redirects, webhook events for Directory Sync), always validate the authenticity of these requests.
• Signature Verification: WorkOS webhooks include a signature in the request header. Verify this signature using your WorkOS webhook secret to ensure the payload hasn't been tampered with and originated from WorkOS. The WorkOS Webhooks documentation provides details on signature verification.
• State Parameter: For OAuth/OIDC flows, use the state parameter to prevent Cross-Site Request Forgery (CSRF) attacks. This parameter should be a unique, unguessable value generated by your application and verified upon callback. The Google Identity documentation on state parameter explains its role in security.
• Implement Least Privilege: Configure your WorkOS integrations with the minimum necessary permissions. For example, if an integration only needs to read directory users, do not grant it permissions to modify them.
• Error Handling and Logging: Implement robust error handling and logging for all authentication-related processes. This helps in identifying and responding to potential security incidents or unauthorized access attempts. Avoid logging sensitive information like raw API keys or user credentials.
• Regular Audits: Periodically review your WorkOS configurations, API key usage, and access logs for any suspicious activity or misconfigurations.
• Keep SDKs Updated: Always use the latest versions of WorkOS SDKs to benefit from security patches and improvements.
• Educate Your Team: Ensure all developers and operations personnel are aware of the security implications of handling API keys and authentication flows.