Skip to main content
This guide will help you set up the WorkOS SDK and authenticate your first user.

​
Step 1: Install the SDK

First, install the WorkOS Node.js SDK: 
npm install @workos-inc/node

​
Step 2: Get your API key

1

Sign in to WorkOS Dashboard

Navigate to the WorkOS Dashboard and sign in to your account.
2

Create an API key

Go to the API Keys section and create a new API key. Copy the key - you’ll need it in the next step.
3

Set environment variable

Add your API key to your environment variables:
.env
WORKOS_API_KEY="sk_test_1234567890"
WORKOS_CLIENT_ID="client_1234567890"
Keep your API key secure! Never commit it to version control or expose it in client-side code.

​
Step 3: Initialize the client

Create a WorkOS client instance. The SDK offers multiple initialization methods: 
import { WorkOS } from '@workos-inc/node';

// Automatically reads WORKOS_API_KEY and WORKOS_CLIENT_ID from environment
const workos = new WorkOS();
This is the recommended approach for server-side applications.

​
Step 4: Authenticate a user

Now let’s authenticate a user using WorkOS AuthKit:
1

Generate an authorization URL

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

const workos = new WorkOS();

const authorizationUrl = workos.userManagement.getAuthorizationUrl({
  provider: 'authkit',
  redirectUri: 'https://your-app.com/callback',
  clientId: workos.clientId!,
});

// Redirect user to authorizationUrl
console.log('Redirect to:', authorizationUrl);
2

Handle the callback

After the user authenticates, WorkOS redirects them back to your callback URL with an authorization code:
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS();

// In your callback route handler
async function handleCallback(code: string) {
  const { user, accessToken, refreshToken } = 
    await workos.userManagement.authenticateWithCode({
      code,
      clientId: workos.clientId!,
    });

  console.log('User:', user);
  console.log('Access token:', accessToken);
  
  return { user, accessToken, refreshToken };
}
3

Get user information

Use the access token to retrieve user information:
const user = await workos.userManagement.getUser({
  userId: user.id,
});

console.log('User email:', user.email);
console.log('User name:', user.firstName, user.lastName);

​
Complete example

Here’s a complete example using Express.js: 
import express from 'express';
import { WorkOS } from '@workos-inc/node';

const app = express();
const workos = new WorkOS();

// Login route - redirect to WorkOS
app.get('/login', (req, res) => {
  const authorizationUrl = workos.userManagement.getAuthorizationUrl({
    provider: 'authkit',
    redirectUri: 'http://localhost:3000/callback',
    clientId: workos.clientId!,
  });
  
  res.redirect(authorizationUrl);
});

// Callback route - handle the response from WorkOS
app.get('/callback', async (req, res) => {
  try {
    const { code } = req.query;
    
    const { user, accessToken } = 
      await workos.userManagement.authenticateWithCode({
        code: code as string,
        clientId: workos.clientId!,
      });
    
    // Store the session and redirect to your app
    res.json({ user, accessToken });
  } catch (error) {
    console.error('Authentication error:', error);
    res.status(500).send('Authentication failed');
  }
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

​
PKCE authentication (for public clients)

For applications that cannot securely store a secret (mobile, CLI, desktop apps), use PKCE: 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS({ clientId: 'client_1234567890' });

// Generate auth URL with PKCE
const { url, codeVerifier } = 
  await workos.userManagement.getAuthorizationUrlWithPKCE({
    provider: 'authkit',
    redirectUri: 'myapp://callback',
    clientId: workos.clientId!,
  });

// Store codeVerifier securely (e.g., iOS Keychain, Android Keystore)
// Redirect user to url

// After callback, exchange code for tokens
const { accessToken, refreshToken } = 
  await workos.userManagement.authenticateWithCode({
    code: authorizationCode,
    codeVerifier, // Retrieved from secure storage
    clientId: workos.clientId!,
  });
For PKCE flows, you must store the codeVerifier securely on-device between generating the authorization URL and handling the callback. The verifier must survive app restarts during the authentication flow.

​
Next steps

Configuration

Learn about advanced configuration options

User Management Guide

Explore user management features

SSO Integration

Set up Single Sign-On for enterprises

API Reference

View the complete API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us