Skip to main content
getWorkOS returns a singleton instance of the WorkOS SDK client, pre-configured with your API key and environment settings. This is useful for accessing WorkOS APIs directly for advanced use cases.

​
Usage

import { getWorkOS } from '@workos-inc/authkit-nextjs';

const workos = getWorkOS();

​
Signature

function getWorkOS(): WorkOS

​
Parameters

This function takes no parameters.

​
Returns

​
workos
WorkOS
The configured WorkOS SDK instance with access to all WorkOS APIs.

​
Examples

​
Listing organizations

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function getOrganizations() {
  const workos = getWorkOS();
  
  const organizations = await workos.organizations.listOrganizations({
    limit: 10,
  });
  
  return organizations.data;
}

​
Creating a new user

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function createUser(email: string, password: string) {
  const workos = getWorkOS();
  
  const user = await workos.userManagement.createUser({
    email,
    password,
    emailVerified: false,
  });
  
  return user;
}

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function sendMagicLink(email: string) {
  const workos = getWorkOS();
  
  await workos.userManagement.sendMagicAuthCode({
    email,
  });
  
  return { success: true };
}

​
Getting organization details

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function getOrganization(organizationId: string) {
  const workos = getWorkOS();
  
  const organization = await workos.organizations.getOrganization({
    organizationId,
  });
  
  return {
    id: organization.id,
    name: organization.name,
    domains: organization.domains,
  };
}

​
Managing organization memberships

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function addUserToOrganization(
  userId: string,
  organizationId: string,
  roleSlug?: string
) {
  const workos = getWorkOS();
  
  const membership = await workos.userManagement.createOrganizationMembership({
    userId,
    organizationId,
    roleSlug,
  });
  
  return membership;
}

​
Updating user metadata

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function updateUserMetadata(
  userId: string,
  metadata: Record<string, unknown>
) {
  const workos = getWorkOS();
  
  const user = await workos.userManagement.updateUser({
    userId,
    firstName: metadata.firstName as string,
    lastName: metadata.lastName as string,
  });
  
  return user;
}

​
Custom email verification

import { NextRequest, NextResponse } from 'next/server';
import { getWorkOS, saveSession } from '@workos-inc/authkit-nextjs';

export async function POST(req: NextRequest) {
  const { code } = await req.json();
  const workos = getWorkOS();
  
  // Verify email with WorkOS
  const authResponse = await workos.userManagement.authenticateWithEmailVerification({
    clientId: process.env.WORKOS_CLIENT_ID!,
    code,
  });
  
  // Save the session
  await saveSession(authResponse, req);
  
  return NextResponse.json({ success: true });
}

​
Querying directory sync data

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function getDirectoryUsers(directoryId: string) {
  const workos = getWorkOS();
  
  const users = await workos.directorySync.listUsers({
    directory: directoryId,
    limit: 100,
  });
  
  return users.data;
}

​
Creating audit log events

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function logEvent(
  organizationId: string,
  action: string,
  actorId: string
) {
  const workos = getWorkOS();
  
  await workos.auditLogs.createEvent({
    organizationId,
    event: {
      action,
      occurredAt: new Date().toISOString(),
      actor: {
        id: actorId,
        type: 'user',
      },
    },
  });
}

​
Checking SSO connection

import { getWorkOS } from '@workos-inc/authkit-nextjs';

export async function checkSSOConnection(organizationId: string) {
  const workos = getWorkOS();
  
  const connections = await workos.sso.listConnections({
    organizationId,
  });
  
  return {
    hasSSOEnabled: connections.data.length > 0,
    connections: connections.data,
  };
}

​
Configuration

The WorkOS instance is configured using environment variables:
  • WORKOS_API_KEY - Your WorkOS API key (required)
  • WORKOS_API_HOSTNAME - Custom API hostname (optional, defaults to api.workos.com)
  • WORKOS_API_HTTPS - Whether to use HTTPS (optional, defaults to true)
  • WORKOS_API_PORT - Custom port (optional)

​
Notes

  • The WorkOS instance is created lazily and cached as a singleton
  • The same instance is reused across all calls to getWorkOS()
  • The instance includes app info headers identifying it as authkit/nextjs
  • All WorkOS SDK methods are available through this instance
  • Use this for advanced use cases not covered by helper functions like withAuth, handleAuth, etc.
  • The full WorkOS Node SDK documentation is available at workos.com/docs

Build docs developers (and LLMs) love

Get started for freeTalk to us