AuthKit Documentation

AuthKit provides two primary ways to implement authentication and user management:

1. Hosted UI: The fastest implementation method. It provides a fully themeable, hosted user interface that manages all authentication flows. For production, you can use a custom domain (e.g., auth.yourapp.com).
2. Custom UI (Headless): Allows you to build your own frontend within your own codebase by integrating directly with the headless WorkOS User Management APIs. In this mode, your authentication UI is self-hosted in your application.

The following implementation patterns are available for building custom authentication flows using AuthKit's headless APIs:

Sign-up Flows

• Email + Password
• Magic Auth

Sign-in Flows

• Email + Password
• Magic Auth
• Google OAuth
• Microsoft OAuth
• Single Sign-On (SSO)

User Management & Security

• Multi-Factor Auth (MFA)
• Verify email
• Reset password
• Users table (Management UI)
• Update user

You can generate a strong password for WORKOS_COOKIE_PASSWORD using openssl on the command line:

openssl rand -base64 24

To test Single Sign-On flows, follow these steps in the WorkOS dashboard:

1. Create an Organization: Navigate to Organizations and select Create organization. Optionally add a domain for members.
2. Create an SSO Connection: On the organization's detail page, navigate to the authentication section and find Single Sign-On.
3. Configure Connection: Use the Configure Manually feature. This requires access to an identity provider (IdP) such as Entra ID (Azure AD), Google Workspace, or Okta.

To use AuthKit with your own frontend using headless User Management APIs, complete the following setup steps:

1. Environment Variables & Redirects: Ensure you have configured your environment variables and redirect URIs as required by WorkOS.
2. Enable Authentication Methods: In your WorkOS dashboard, navigate to Authentication and ensure the specific authentication methods you intend to use (e.g., Google OAuth, Microsoft OAuth, Email + Password) are set to Enabled.
3. OAuth Testing: For Google and Microsoft OAuth, you can use WorkOS demo app credentials in your WorkOS staging environment to test flows without setting up your own OAuth apps.
4. SSO Configuration: If testing Single Sign-On, you must create an organization in the WorkOS dashboard and set up a Single Sign-On connection (using Configure Manually) for that organization.

Follow these steps to run the local development environment:

1. Install dependencies: npm install or yarn install.
2. Configure environment variables in .env.local (see Set up AuthKit environment variables).
3. Configure redirect URLs in the WorkOS dashboard (see Configure WorkOS redirect URLs).
4. Start the development server: npm run dev or yarn dev.
5. Access the application at http://localhost:3000.

You must whitelist redirect URLs in the WorkOS dashboard under the Redirects section to allow authentication callbacks to function correctly.

For the local development example, add the following URLs:

http://localhost:3000/using-your-own-ui/sign-in/google-oauth/callback
http://localhost:3000/using-your-own-ui/sign-in/microsoft-oauth/callback
http://localhost:3000/using-your-own-ui/sign-in/github-oauth/callback
http://localhost:3000/using-your-own-ui/sign-in/sso/callback
http://localhost:3000/using-hosted-authkit/basic/callback
http://localhost:3000/using-hosted-authkit/with-session/callback
http://localhost:3000/using-hosted-authkit/with-nextjs/callback

To use the Single Sign-On (SSO) flow with your own UI, follow these steps in the WorkOS dashboard:

1. Create an Organization: Navigate to Organizations and select Create organization. You may optionally add a domain.
2. Create SSO Connection: On the organization's detail page, go to the authentication section, find Single Sign-On, and use the Configure Manually feature to create a new connection. This requires an identity provider (IdP) like Entra ID, Google Workspace, or Okta.
3. Set Environment Variable: Copy the Organization ID (starting with org_) from the organization's detail page and add it to your .env.local file.

SSO_ENABLED_ORGANIZATION_ID="<your Organization ID>"

To use AuthKit, you must provide your WorkOS credentials. Obtain your Client ID and Secret Key (API Key) from the API Keys section of the WorkOS dashboard.

Create a .env.local file in your project root and populate it with the following variables:

WORKOS_CLIENT_ID="<your Client ID>"
WORKOS_API_KEY="<your Secret Key>"

When using the authkit-nextjs library, you must define the following environment variables:

• WORKOS_REDIRECT_URI: The redirect URI defined in your WorkOS dashboard.
• WORKOS_COOKIE_PASSWORD: A secure password that must be at least 32 characters long.

# Needed for authkit-nextjs library example, defined in WorkOS dashboard
WORKOS_REDIRECT_URI=

# Needed for authkit-nextjs library example. Must be at least 32 characters long
WORKOS_COOKIE_PASSWORD=