WorkOS Getting Started: Account Setup & First API Request (2026)

Getting started overview

Integrating WorkOS involves a series of steps designed to enable enterprise-grade features within a B2B SaaS application. This guide focuses on the initial setup, including account creation, retrieving API credentials, and executing a foundational API request. The process typically begins with creating a WorkOS account, followed by project configuration within the WorkOS Admin Portal, and then integrating the WorkOS SDK into your application to handle authentication and directory synchronization tasks.

WorkOS primarily serves developers building B2B SaaS products who need to implement features like Single Sign-On (SSO) with SAML or OIDC, Directory Sync (SCIM), or Audit Logs for their enterprise customers WorkOS product guides overview. The platform abstracts the complexities of integrating with various enterprise identity providers and directories, providing a unified API surface WorkOS API reference. By following these steps, developers can prepare their application to interact with WorkOS services.

Create an account and get keys

The first step in integrating WorkOS is to create a free developer account. WorkOS offers a free tier that supports up to 1 million monthly active users (MAUs) across its AuthKit, SSO, and SCIM products, allowing for development and testing without immediate cost WorkOS pricing details. After creating your account, you will be directed to the WorkOS Admin Portal, which serves as the central hub for managing your projects, configurations, and API keys.

Account Creation

1. Navigate to the WorkOS signup page.
2. Enter your email address and create a password, or sign up using a third-party identity provider.
3. Verify your email address if prompted.

Project Setup

Upon logging into the Admin Portal, you'll need to create a project to house your WorkOS configurations and API keys. A project typically corresponds to a single application or environment (e.g., 'Production App', 'Staging App').

1. From the WorkOS Admin Portal dashboard, click on 'Create new project' or navigate to the 'Projects' section.
2. Provide a descriptive name for your project (e.g., "My SaaS Production").
3. Select the region that best suits your deployment needs.

Retrieving API Keys

WorkOS uses two primary credentials for authentication: your API Key and your Client ID. The API Key is a secret credential used for server-side operations, while the Client ID is a public identifier for your application, often used in client-side authentication flows. Securing your API Key is critical, as it grants access to your WorkOS resources WorkOS authentication guide.

1. In your WorkOS Admin Portal, navigate to your newly created project.
2. On the left sidebar, click on 'Configuration' and then 'API Keys'.
3. You will find your 'API Key' and 'Client ID' listed. Copy these values and store them securely. Your API Key should be treated as sensitive information, similar to a database password, and should not be exposed in client-side code.

Configuring Redirect URIs

For authentication flows, especially those involving protocols like OAuth 2.0 or OpenID Connect, it's necessary to register Redirect URIs with WorkOS. These URIs are the locations to which WorkOS will send the user's browser after successful authentication. This is a standard security measure to prevent phishing and ensure callbacks are only sent to trusted locations, as outlined in RFC 6749 for OAuth 2.0 OAuth 2.0 Redirection Endpoint.

1. In the WorkOS Admin Portal, within your project, navigate to 'Configuration' and then 'AuthKit'.
2. Under 'Redirect URIs', add all valid callback URLs for your development, staging, and production environments. For example, http://localhost:3000/auth/callback for local development.
3. Click 'Save Changes'.

Your first request

Making your first request typically involves installing a WorkOS SDK and then using it to perform an initial operation, such as generating an SSO authorization URL. This example uses the Node.js SDK, but similar patterns apply to other supported languages like Python, Ruby, PHP, Go, Java, and .NET WorkOS SDKs documentation.

1. Install the SDK

First, install the WorkOS SDK for your chosen programming language. For Node.js:

npm install @workos-inc/node
# or
yarn add @workos-inc/node

2. Initialize the WorkOS client

In your application code, import and initialize the WorkOS client using your API Key. It's recommended to load your API Key from environment variables to keep it secure.

// Import the WorkOS Node.js SDK
const { WorkOS } = require('@workos-inc/node');

// Initialize the WorkOS client with your API Key
// It's best practice to load this from an environment variable
const workos = new WorkOS(process.env.WORKOS_API_KEY);

// You can also specify the client ID, although it's often inferred by the SDK
// workos.setClientInfo({
//   clientId: process.env.WORKOS_CLIENT_ID
// });

3. Make a basic API call: Generate an SSO Authorization URL

A common first step for integrating SSO is to generate an authorization URL. This URL is where your application will redirect users to initiate the SSO flow with their enterprise identity provider. This example assumes you are using WorkOS's Admin Portal to allow your customers to configure their SSO connection.

async function generateSsoAuthUrl() {
  try {
    const authorizationUrl = workos.sso.getAuthorizationUrl({
      // The Client ID for your project. This is found in the WorkOS Admin Portal
      clientId: process.env.WORKOS_CLIENT_ID,
      
      // The redirect URI where users will be sent after authenticating
      // This must be one of the Redirect URIs configured in your WorkOS Admin Portal
      redirectUri: 'http://localhost:3000/auth/callback',
      
      // The response type expected from the authorization server. For SSO, this is usually 'code'.
      responseType: 'code',
      
      // An optional domain to pre-fill the SSO flow. Useful if you know the user's domain.
      // For initial testing, you might leave this out or use a test domain.
      // domain: 'example.com',
      
      // An optional provider to pre-fill the SSO flow. Also useful if you know the provider.
      // provider: 'GoogleOAuth',

      // Optional state parameter for CSRF protection and to maintain state between the request and callback.
      // This should be a cryptographically secure random string.
      state: 'your_secure_random_state_string'
    });

    console.log('SSO Authorization URL:', authorizationUrl);
    // In a real application, you would redirect the user to this URL.
    // res.redirect(authorizationUrl);

    return authorizationUrl;

  } catch (error) {
    console.error('Error generating SSO Authorization URL:', error);
    throw error;
  }
}

generateSsoAuthUrl();

When implementing this in a web application, the generated authorizationUrl would typically be used to redirect the user's browser. After the user authenticates with their identity provider, they will be redirected back to your redirectUri with an authorization code, which you can then exchange for user profile information using the WorkOS SDK.

Common next steps

Once you've made your first successful API call, several common next steps will further integrate WorkOS into your application's enterprise features:

1. Handle the SSO Callback: Implement the logic on your redirectUri endpoint to receive the authorization code, exchange it for an access token and user profile via WorkOS, and then create or log in the user in your application WorkOS SSO integration guide.
2. Configure and Test SSO Connections: Use the WorkOS Admin Portal to set up and test SSO connections with various identity providers (e.g., Okta, Azure AD, Google Workspace). You can often provide your customers with access to a dedicated Admin Portal for self-service configuration WorkOS Admin Portal documentation.
3. Implement Directory Sync (SCIM): If your application requires syncing user and group information from enterprise directories, integrate the Directory Sync API. This involves setting up webhooks to receive updates from WorkOS about changes in the customer's directory WorkOS Directory Sync guide.
4. Integrate Audit Logs: For enterprise compliance and security monitoring, integrate Audit Logs. This typically involves sending critical events from your application to WorkOS, which then makes them available to your customers through their Admin Portal WorkOS Audit Logs documentation.
5. Refine Error Handling and Logging: Implement robust error handling and logging for all WorkOS API interactions to aid in debugging and production monitoring.
6. Secure Production Credentials: Ensure all API keys and sensitive configurations are managed securely using environment variables, secret management services, or other best practices for production environments, as recommended for any API platform like Stripe Stripe API keys documentation.

Troubleshooting the first call

Encountering issues during the initial setup of any API integration is common. Here are some troubleshooting tips for your first WorkOS API call:

• Invalid API Key/Client ID: Double-check that your WORKOS_API_KEY and WORKOS_CLIENT_ID are copied correctly from the WorkOS Admin Portal and are loaded into your environment variables without extra spaces or characters. Ensure the API Key is used for server-side requests and the Client ID for client-side context where applicable.
• Incorrect Redirect URI: This is a frequent source of errors. Verify that the redirectUri passed in your getAuthorizationUrl call exactly matches one of the 'Redirect URIs' configured in your WorkOS Admin Portal for the specific project. Pay attention to schemes (http vs. https), hostnames (localhost vs. a domain), and paths. An exact match is required for security WorkOS redirect URI configuration.
• Environment Variables Not Loaded: If you're using process.env, ensure your environment variables are correctly loaded into your application's runtime. For Node.js, this often involves using a library like dotenv in development or configuring them directly in your deployment environment.
• Network or Firewall Issues: Confirm that your application server has outbound network access to WorkOS API endpoints (api.workos.com). If you are in a restricted network environment, you might need to configure firewall rules.
• SDK Version Compatibility: Ensure you are using a compatible version of the WorkOS SDK for your programming language and runtime environment. Refer to the official WorkOS SDK documentation for version requirements.
• WorkOS Admin Portal Status: Check the WorkOS status page for any ongoing service disruptions or outages that might affect API calls WorkOS Status Page.
• Logging and Debugging: Utilize your application's logging framework to output detailed information about the API request and response. The WorkOS SDKs often provide internal logging capabilities that can be enabled for more verbose output during debugging.
• Consult WorkOS Docs and Support: If you're stuck, the extensive WorkOS documentation is an excellent resource. For persistent issues, reaching out to WorkOS support with relevant error messages and request IDs can help diagnose the problem WorkOS developer documentation.