AuthKit

https://github.com/workos/authkit
Admin
AuthKit provides flexible authentication solutions, allowing you to use its hosted UI or build your...
Tokens:32,660
Snippets:372
Trust Score:9.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Sign-up URL Generation Examples

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Examples demonstrating basic usage and organization-scoped sign-up URL generation.

```typescript
import { getSignUpUrl } from '@workos-inc/authkit-nextjs';

export default async function SignUpPage() {
  const signUpUrl = await getSignUpUrl();
  return <a href={signUpUrl}>Sign Up</a>;
}
```

```typescript
const signUpUrl = await getSignUpUrl({
  organizationId: 'org_123456',
  returnTo: '/onboarding'
});
```

--------------------------------

### signOut usage examples

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Examples demonstrating basic sign-out and sign-out with a redirect URL.

```typescript
import { signOut } from '@workos-inc/authkit-nextjs';

export default function UserMenu() {
  return (
    <button onClick={() => signOut()}>
      Sign Out
    </button>
  );
}
```

```typescript
const handleLogout = async () => {
  await signOut({ returnTo: '/login' });
};
```

--------------------------------

### switchToOrganization usage examples

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Examples demonstrating switching organizations and performing cache revalidation during the switch.

```typescript
import { switchToOrganization } from '@workos-inc/authkit-nextjs';

const handleOrgSwitch = async (orgId: string) => {
  const userInfo = await switchToOrganization(orgId);
  console.log('Switched to organization:', userInfo.organizationId);
};
```

```typescript
const userInfo = await switchToOrganization('org_789', {
  returnTo: '/org-dashboard',
  revalidationStrategy: 'tag',
  revalidationTags: ['org-data']
});
```

--------------------------------

### Get WorkOS SDK Instance Usage

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Examples for accessing the WorkOS client instance in user management, server actions, and route handlers.

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

const workos = getWorkOS();

// Create a user
const user = await workos.userManagement.createUser({
  clientId: process.env.WORKOS_CLIENT_ID,
  email: 'user@example.com',
  password: 'secure-password-123'
});

// List users
const users = await workos.userManagement.listUsers({
  clientId: process.env.WORKOS_CLIENT_ID,
  limit: 10
});

// Get user by ID
const user = await workos.userManagement.getUser(userId);

// Update user
const updated = await workos.userManagement.updateUser(userId, {
  firstName: 'New',
  lastName: 'Name'
});
```

```typescript
'use server';

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

export async function createInvitation(email: string) {
  const workos = getWorkOS();
  
  const invitation = await workos.userManagement.sendInvitation({
    clientId: process.env.WORKOS_CLIENT_ID,
    email: email,
    acceptanceUrl: 'https://example.com/accept-invitation'
  });
  
  return invitation;
}
```

```typescript
import { getWorkOS } from '@workos-inc/authkit-nextjs';
import { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const workos = getWorkOS();
  
  const users = await workos.userManagement.listUsers({
    clientId: process.env.WORKOS_CLIENT_ID
  });
  
  return Response.json(users);
}
```

--------------------------------

### Implement re-authentication prompt

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Example showing how to trigger a re-authentication UI when the session is stale.

```typescript
import { useRecentAuth } from '@workos-inc/authkit-nextjs/components';

export function SensitiveAction() {
  const recentAuth = useRecentAuth({ maxAge: 300 }); // 5 minutes
  
  if (recentAuth.loading) {
    return <div>Checking authentication...</div>;
  }
  
  if (recentAuth.isStale) {
    return <button onClick={handleReAuth}>Re-authenticate Required</button>;
  }
  
  return <button onClick={handleAction}>Perform Action</button>;
}
```

--------------------------------

### Display User Information

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Example of accessing user data and handling loading states.

```typescript
import { useAuth } from '@workos-inc/authkit-nextjs/components';

export function UserProfile() {
  const { user, loading } = useAuth();
  
  if (loading) return <div>Loading...</div>;
  if (!user) return <div>Not signed in</div>;
  
  return <div>Welcome, {user.email}</div>;
}
```

--------------------------------

### Sign-in with Return Path and Hint

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Example of generating a sign-in URL with custom return path and login hint parameters.

```typescript
const signInUrl = await getSignInUrl({
  returnTo: '/dashboard',
  loginHint: 'user@example.com'
});
```

--------------------------------

### Basic Sign-in Redirect

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Example of generating a sign-in URL within a Next.js server component.

```typescript
import { getSignInUrl } from '@workos-inc/authkit-nextjs';

export default async function SignInPage() {
  const signInUrl = await getSignInUrl();
  return <a href={signInUrl}>Sign In</a>;
}
```

--------------------------------

### Display last authentication time

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Example showing how to format and display the timestamp of the user's last authentication.

```typescript
const recentAuth = useRecentAuth({ maxAge: 3600 });

if (recentAuth.authenticatedAt) {
  const lastAuth = recentAuth.authenticatedAt.toLocaleString();
  return <p>Last authenticated: {lastAuth}</p>;
}
```

--------------------------------

### Update Environment Variables for Sessions

Source: https://github.com/workos/authkit/blob/main/src/app/using-hosted-authkit/README.md

Example configuration for adding the JWT secret to the local environment file.

```bash
# ...
JWT_SECRET_KEY="<your JWT secret>"
```

--------------------------------

### Get User Entitlements

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Checks for license-based entitlements for a signed-in user.

```typescript
const { entitlements } = await withAuth({ ensureSignedIn: true });

if (entitlements?.includes('sso')) {
  // User has SSO license
}
```

--------------------------------

### Validate API Key Usage

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Examples for validating the WorkOS API key during application startup or within Next.js instrumentation.

```typescript
import { validateApiKey } from '@workos-inc/authkit-nextjs';

export async function validateEnvironment() {
  try {
    await validateApiKey();
    console.log('WorkOS API key is valid');
  } catch (error) {
    console.error('Invalid WorkOS API key:', error.message);
    process.exit(1);
  }
}

// Call during app initialization
if (process.env.NODE_ENV === 'production') {
  await validateEnvironment();
}
```

```typescript
// instrumentation.ts
import { validateApiKey } from '@workos-inc/authkit-nextjs';

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    try {
      await validateApiKey();
    } catch (error) {
      console.error('Failed to validate WorkOS credentials');
      throw error;
    }
  }
}
```

--------------------------------

### Retrieve fresh token for API calls

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Example of using getAccessToken to ensure a fresh token is available before making an API request.

```typescript
const { getAccessToken } = useAccessToken();

const handleApiCall = async () => {
  try {
    const token = await getAccessToken();
    const response = await fetch('/api/data', {
      headers: { Authorization: `Bearer ${token}` }
    });
  } catch (error) {
    console.error('Token retrieval failed:', error);
  }
};
```

--------------------------------

### Display current access token

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Example of using the hook to display the current access token in a component.

```typescript
import { useAccessToken } from '@workos-inc/authkit-nextjs/components';

export function TokenDisplay() {
  const { accessToken, loading } = useAccessToken();
  
  if (loading) return <div>Loading token...</div>;
  if (!accessToken) return <div>No token</div>;
  
  return <code>{accessToken.substring(0, 20)}...</code>;
}
```

--------------------------------

### Get WorkOS SDK Instance Definition

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Type definition for the getWorkOS function.

```typescript
function getWorkOS(): WorkOS
```

--------------------------------

### Check AuthKit SDK Version

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Use the exported VERSION constant to verify the installed SDK version for debugging or feature compatibility checks.

```typescript
import { VERSION } from '@workos-inc/authkit-nextjs';

console.log(`AuthKit version: ${VERSION}`);
// Output: "AuthKit version: 2.14.0"
```

--------------------------------

### Getting Access Token

Source: https://github.com/workos/authkit/blob/main/_autodocs/README.md

Retrieve an access token for authenticating outgoing API requests.

```typescript
// For API calls
const { getAccessToken } = useAccessToken();
const token = await getAccessToken();

// Make API call
fetch('/api/data', {
  headers: { Authorization: `Bearer ${token}` }
});
```

--------------------------------

### Access standard JWT claims

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Example of extracting and displaying standard claims from the current access token.

```typescript
import { useTokenClaims } from '@workos-inc/authkit-nextjs/components';

export function ClaimsDisplay() {
  const claims = useTokenClaims();
  
  return (
    <div>
      <p>User: {claims.sub}</p>
      <p>Organization: {claims.org_id}</p>
      <p>Expires: {new Date(claims.exp * 1000).toISOString()}</p>
    </div>
  );
}
```

--------------------------------

### Access session in route handler

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/middleware.md

Demonstrates how to retrieve the session and handle unauthorized requests in a Next.js GET route handler.

```typescript
import { authkit } from '@workos-inc/authkit-nextjs';
import { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const { session } = await authkit(request);
  
  if (!session.user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
  
  return Response.json({ user: session.user });
}
```

--------------------------------

### Get User

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Retrieve a specific user by their unique identifier.

```typescript
const user = await workos.userManagement.getUser(userId);
```

--------------------------------

### Create Organization with TypeScript

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Initializes a new organization with a specified name and verified domain.

```typescript
const org = await workos.organizations.createOrganization({
  name: 'Acme Corp',
  domainData: [
    {
      domain: 'acme.com',
      state: 'verified'
    }
  ]
});
```

--------------------------------

### Get Invitation Details

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Retrieves the details of a specific invitation by its ID.

```typescript
const invitation = await workos.userManagement.getInvitation(invitationId);
```

--------------------------------

### Initialize WorkOS Client

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Access the WorkOS SDK instance through the AuthKit package.

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

const workos = getWorkOS();
```

--------------------------------

### Get Organization with TypeScript

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Retrieves details for a specific organization by its ID.

```typescript
const org = await workos.organizations.getOrganization(organizationId);
```

--------------------------------

### Get API Key

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Retrieves details for a specific API key by its ID.

```typescript
const apiKey = await workos.apiKeys.getApiKey(apiKeyId);
```

--------------------------------

### Get Organization Membership with TypeScript

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Retrieves details for a specific membership by its ID.

```typescript
const membership = await workos.organizationMemberships.getOrganizationMembership(
  membershipId
);
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/workos/authkit/blob/main/README.md

Set the required WorkOS credentials in your .env.local file.

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

--------------------------------

### Set OAuth/OIDC screen hints

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Use screenHint to force the display of either the sign-in or sign-up screen when generating authentication URLs.

```typescript
// Force sign-in screen
const signInUrl = await getSignInUrl({ screenHint: 'sign-in' });

// Force sign-up screen
const signUpUrl = await getSignUpUrl({ screenHint: 'sign-up' });
```

--------------------------------

### getSignUpUrl()

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Generates a sign-up URL for redirecting users to the registration flow.

```APIDOC
## getSignUpUrl()

### Description
Generates a sign-up URL for redirecting users to the registration flow.

### Signature
`getSignUpUrl(authUrlOptions?: GetSignUrlOptions): Promise<string>`

### Parameters
- **authUrlOptions** (GetSignUrlOptions) - Optional - Configuration options for the sign-up URL
  - **returnTo** (string) - Optional - URL to redirect to after successful sign-up
  - **organizationId** (string) - Optional - Organization ID to scope the sign-up to a specific organization
  - **redirectUri** (string) - Optional - Custom redirect URI (overrides default)
  - **loginHint** (string) - Optional - Pre-populate the email field with a hint
  - **prompt** ('consent') - Optional - Force consent screen to be shown
  - **state** (string) - Optional - Custom state parameter for CSRF protection

### Returns
- **Promise<string>** - Resolves to the complete sign-up URL.

### Throws
- **AuthKitError** - Thrown if required environment variables are missing.

### Example
```typescript
import { getSignUpUrl } from '@workos-inc/authkit-nextjs';

const signUpUrl = await getSignUpUrl({
  organizationId: 'org_123456',
  returnTo: '/onboarding'
});
```
```

--------------------------------

### Implement Email/Password Sign-In Server Action

Source: https://github.com/workos/authkit/blob/main/_autodocs/integration-guide.md

Handles authentication logic on the server using the WorkOS client and saves the session upon success.

```typescript
// app/sign-in/actions.ts
'use server';

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

export async function handleEmailPasswordSignIn(
  email: string,
  password: string,
  request: NextRequest
) {
  try {
    const workos = getWorkOS();
    
    const response = await workos.userManagement.authenticateWithPassword({
      clientId: process.env.WORKOS_CLIENT_ID!,
      email,
      password
    });
    
    await saveSession(response, request);
    
    return { success: true };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Sign-in failed'
    };
  }
}
```

--------------------------------

### Get User Features

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Checks for specific feature flags associated with a signed-in user.

```typescript
const { user } = await withAuth({ ensureSignedIn: true });
const { featureFlags } = await refreshSession();

if (featureFlags?.includes('premium-analytics')) {
  // Show premium feature
}
```

--------------------------------

### Get Audit Logs

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Retrieves a list of audit log events for a specific client.

```typescript
const { data: logs } = await workos.auditLogs.listEvents({
  clientId: process.env.WORKOS_CLIENT_ID,
  limit: 100
});

// logs[].eventName - 'user.created', 'user.updated', etc.
// logs[].actor - who performed the action
// logs[].targets - what was affected
// logs[].occurredAt - timestamp
```

--------------------------------

### workos.userManagement.listInvitations

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Lists all invitations for a client.

```APIDOC
## workos.userManagement.listInvitations

### Description
Lists all invitations associated with a specific client.

### Parameters
- **clientId** (string) - Required - The WorkOS client ID.
```

--------------------------------

### Configure Redirect URLs

Source: https://github.com/workos/authkit/blob/main/README.md

List of callback URLs required for OAuth and SSO authentication flows.

```bash
http://localhost:3000/using-your-own-ui/sign-in/google-oauth/callback
```

```bash
http://localhost:3000/using-your-own-ui/sign-in/microsoft-oauth/callback
```

```bash
http://localhost:3000/using-your-own-ui/sign-in/github-oauth/callback
```

```bash
http://localhost:3000/using-your-own-ui/sign-in/sso/callback
```

```bash
http://localhost:3000/using-hosted-authkit/basic/callback
```

```bash
http://localhost:3000/using-hosted-authkit/with-session/callback
```

```bash
http://localhost:3000/using-hosted-authkit/with-nextjs/callback
```

--------------------------------

### Create Sign-In Page

Source: https://github.com/workos/authkit/blob/main/_autodocs/README.md

Generate a sign-in URL to direct users to the authentication flow.

```typescript
// app/sign-in/page.tsx
import { getSignInUrl } from '@workos-inc/authkit-nextjs';

export default async function SignInPage() {
  const signInUrl = await getSignInUrl();
  return <a href={signInUrl}>Sign In</a>;
}
```

--------------------------------

### Retrieve raw session cookie

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/session-management.md

Example usage of getSessionFromCookie to access session data and user information.

```typescript
import { getSessionFromCookie } from '@workos-inc/authkit-nextjs';

const session = await getSessionFromCookie();

if (session) {
  console.log(session.accessToken, session.user.id);
}
```

--------------------------------

### handleAuth(options)

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Configures authentication flow behavior for route handlers.

```APIDOC
## handleAuth(options)

### Description
Configures the authentication flow, including return paths and custom success/error handling.

### Parameters
- **returnPathname** (string) - Optional - Path to redirect to after successful authentication.
- **baseURL** (string) - Optional - Base URL for redirects.
- **onSuccess** (function) - Optional - Callback executed upon successful authentication.
- **onError** (function) - Optional - Callback for custom error handling.
```

--------------------------------

### Configure token refresh callbacks

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/middleware.md

Shows how to use refresh buffer settings and callbacks to handle session token lifecycle events.

```typescript
const { session, headers } = await authkit(request, {
  refreshBufferSeconds: 60,
  onSessionRefreshSuccess: async ({ accessToken, user }) => {
    console.log(`Session refreshed for ${user.email}`);
  },
  onSessionRefreshError: async ({ error }) => {
    console.error('Session refresh failed:', error);
  }
});
```

--------------------------------

### authkit(request, options)

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Configures token management and OAuth behavior for route handlers.

```APIDOC
## authkit(request, options)

### Description
Configures session management and OAuth parameters for route handlers.

### Parameters
- **eagerAuth** (boolean) - Optional - Proactively refresh tokens before expiry.
- **refreshBufferSeconds** (number) - Optional - Seconds before token expiry to refresh.
- **debug** (boolean) - Optional - Log operations to console.
- **redirectUri** (string) - Optional - Custom OAuth redirect URI.
- **screenHint** (string) - Optional - Hint for the authentication screen (e.g., 'sign-in').
- **onSessionRefreshSuccess** (function) - Optional - Callback triggered on successful session refresh.
- **onSessionRefreshError** (function) - Optional - Callback triggered on session refresh failure.
```

--------------------------------

### Configure handleAuth() Route Handler

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Define return paths, base URLs, and custom success or error handling logic for authentication routes.

```typescript
export const GET = handleAuth({
  // Return path after successful auth
  returnPathname: '/dashboard',
  
  // Base URL for redirects
  baseURL: 'https://example.com',
  
  // Success callback
  onSuccess: async (data) => {
    console.log(`${data.user.email} authenticated via ${data.authenticationMethod}`);
    // Log to analytics, create audit log, etc.
  },
  
  // Custom error handling
  onError: async ({ error, request }) => {
    if (error instanceof CallbackError) {
      return Response.json(
        { error: error.code },
        { status: 400 }
      );
    }
    return Response.json(
      { error: 'Authentication failed' },
      { status: 500 }
    );
  }
});
```

--------------------------------

### Initialize Feature Flags Runtime Client

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Defines the signature for the client initialization function.

```typescript
function getFeatureFlagsRuntimeClient(
  options?: RuntimeClientOptions
): FeatureFlagsRuntimeClient
```

--------------------------------

### Access custom JWT claims

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Example of using a generic type parameter to access custom claims defined in the JWT.

```typescript
interface CustomClaims {
  department: string;
  tier: 'free' | 'pro' | 'enterprise';
}

const claims = useTokenClaims<CustomClaims>();

if (claims.tier === 'enterprise') {
  return <PremiumFeatures />;
}
```

--------------------------------

### Create User

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Create a new user record using the WorkOS client.

```typescript
const user = await workos.userManagement.createUser({
  clientId: process.env.WORKOS_CLIENT_ID,
  email: 'user@example.com',
  password: 'secure-password',
  firstName: 'John',
  lastName: 'Doe'
});
```

--------------------------------

### Create Organization via Server Action

Source: https://github.com/workos/authkit/blob/main/_autodocs/integration-guide.md

Creates a new organization and assigns the current user as an owner using WorkOS server-side utilities.

```typescript
// app/create-org/actions.ts
'use server';

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

export async function createOrganization(name: string) {
  const { user } = await withAuth({ ensureSignedIn: true });
  const workos = getWorkOS();
  
  const org = await workos.organizations.createOrganization({
    name
  });
  
  // Add user as organization member
  await workos.organizationMemberships.createOrganizationMembership({
    organizationId: org.id,
    userId: user.id,
    roleId: 'owner'  // Or appropriate role
  });
  
  return org;
}
```

--------------------------------

### Implement Next.js middleware

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Sets up the AuthKit proxy in middleware.ts to handle authentication routes.

```typescript
import { authkitProxy } from '@workos-inc/authkit-nextjs';

export const middleware = authkitProxy();

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

--------------------------------

### Configure Next.js Environment Variables

Source: https://github.com/workos/authkit/blob/main/src/app/using-hosted-authkit/README.md

Required environment variables for the authkit-nextjs library integration.

```bash
# Needed for authkit-nextjs library example, defined in WorkOS dashboard
NEXT_PUBLIC_WORKOS_REDIRECT_URI=

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

--------------------------------

### Initialize AuthKitProvider with server-side auth

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

Pass initial authentication state retrieved from the server to the provider to skip the initial client-side fetch.

```typescript
// app/layout.tsx
import { withAuth } from '@workos-inc/authkit-nextjs';

export default async function RootLayout({ children }) {
  const initialAuth = await withAuth();
  
  return (
    <AuthKitProvider initialAuth={initialAuth}>
      {children}
    </AuthKitProvider>
  );
}
```

--------------------------------

### Get session with optional authentication

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/session-management.md

Retrieves session data without enforcing sign-in, allowing for conditional rendering based on user presence.

```typescript
import { withAuth } from '@workos-inc/authkit-nextjs';

export default async function Dashboard() {
  const { user, sessionId } = await withAuth();
  
  if (!user) {
    return <div>Please sign in</div>;
  }
  
  return <div>Welcome, {user.email}</div>;
}
```

--------------------------------

### handleAuth(options)

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/middleware.md

Creates a Next.js route handler to process OAuth callbacks.

```APIDOC
## handleAuth(options)

### Description
Creates a Next.js route handler for processing OAuth callbacks. This function is intended to be used within a Next.js API route file.

### Signature
`function handleAuth(options?: HandleAuthOptions): (request: NextRequest) => Promise<Response>`

### Parameters
- **options** (HandleAuthOptions) - Optional - Callback handling options
  - **returnPathname** (string) - Optional - Path to redirect to after successful authentication (Default: '/')
  - **baseURL** (string) - Optional - Base URL for building redirect URLs
  - **onSuccess** (function) - Optional - Callback on successful authentication
  - **onError** (function) - Optional - Custom error response handler

### Returns
- A Next.js route handler function that processes OAuth callbacks.

### Throws
- `CallbackError` if callback validation fails (missing params, state mismatch, etc.)

### Examples

**Basic callback route:**
```typescript
// app/api/auth/callback/route.ts
import { handleAuth } from '@workos-inc/authkit-nextjs';

export const GET = handleAuth({
  returnPathname: '/dashboard'
});
```

**With success callback:**
```typescript
export const GET = handleAuth({
  returnPathname: '/dashboard',
  onSuccess: async (data) => {
    console.log(`User ${data.user.email} authenticated`);
  }
});
```

**With custom error handling:**
```typescript
export const GET = handleAuth({
  onError: async ({ error, request }) => {
    console.error('Auth error:', error);
    if (error instanceof CallbackError) {
      return Response.json({ error: error.code }, { status: 400 });
    }
    return Response.json({ error: 'Authentication failed' }, { status: 500 });
  }
});
```
```

--------------------------------

### Wrap Application with AuthKitProvider

Source: https://github.com/workos/authkit/blob/main/_autodocs/README.md

Provide authentication context to your application components in the root layout.

```typescript
// app/layout.tsx
import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AuthKitProvider>
          {children}
        </AuthKitProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Importing and using WorkOS TypeScript types

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Demonstrates importing core WorkOS types and using them to type-check API responses.

```typescript
import type {
  User,
  Organization,
  OrganizationMembership,
  AuthenticationResponse,
  OauthTokens,
  Invitation
} from '@workos-inc/node';

const user: User = await workos.userManagement.getUser(userId);
const org: Organization = await workos.organizations.getOrganization(orgId);
```

--------------------------------

### workos.userManagement.sendInvitation

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Sends an invitation to a new user.

```APIDOC
## workos.userManagement.sendInvitation

### Description
Sends an invitation to a new user via email.

### Parameters
- **clientId** (string) - Required - The WorkOS client ID.
- **email** (string) - Required - The email address of the user to invite.
- **acceptanceUrl** (string) - Required - The URL the user is redirected to upon accepting the invitation.
```

--------------------------------

### switchToOrganization()

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Switches the authenticated user's active organization context.

```APIDOC
## switchToOrganization()

### Description
Switches the authenticated user's active organization context.

### Signature
`function switchToOrganization(organizationId: string, options?: SwitchToOrganizationOptions): Promise<UserInfo>`

### Parameters
- **organizationId** (string) - Required - The ID of the organization to switch to
- **options** (SwitchToOrganizationOptions) - Optional - Switch options
  - **returnTo** (string) - Optional - URL to redirect to after switching
  - **revalidationStrategy** ('none' | 'tag' | 'path') - Optional - Next.js revalidation strategy for cache invalidation
  - **revalidationTags** (string[]) - Optional - Array of Next.js revalidation tags to invalidate

### Returns
Promise resolving to `UserInfo` containing updated user data with the new organization context.

### Throws
- `AuthKitError` if organization switch fails
- Error if user is not authenticated
```

--------------------------------

### Environment Variable Configuration

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Required environment variables for development and production AuthKit deployments.

```bash
# .env.local
WORKOS_API_KEY=sk_test_...
WORKOS_CLIENT_ID=project_test_...
WORKOS_COOKIE_PASSWORD=... (32-char base64)
WORKOS_REDIRECT_URI=http://localhost:3000/api/auth/callback
```

```bash
# .env.production
WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=project_live_...
WORKOS_COOKIE_PASSWORD=... (different 32-char base64)
WORKOS_REDIRECT_URI=https://yourdomain.com/api/auth/callback
WORKOS_COOKIE_DOMAIN=.yourdomain.com
WORKOS_COOKIE_SAMESITE=strict
```

--------------------------------

### workos.apiKeys.listApiKeys

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Lists API keys for the application.

```APIDOC
## workos.apiKeys.listApiKeys

### Description
Retrieves a list of API keys associated with the application.

### Parameters
- **limit** (number) - Optional - The maximum number of keys to return.
```

--------------------------------

### Configure authkit() Route Handler

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Configure token management, OAuth settings, and session refresh callbacks within route handlers.

```typescript
const { session, headers } = await authkit(request, {
  // Token management
  eagerAuth: true,
  refreshBufferSeconds: 60,
  
  // Logging
  debug: false,
  
  // OAuth
  redirectUri: 'https://example.com/api/auth/callback',
  screenHint: 'sign-in',
  
  // Callbacks
  onSessionRefreshSuccess: async ({ accessToken, user }) => {
    console.log(`Session refreshed for ${user.email}`);
  },
  onSessionRefreshError: async ({ error }) => {
    console.error('Session refresh failed:', error);
  }
});
```

--------------------------------

### Configure Impersonation

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Add the Impersonation component to layouts and check for impersonation status in server-side code.

```typescript
import { Impersonation } from '@workos-inc/authkit-nextjs/components';

export default function Layout({ children }) {
  return (
    <>
      <Impersonation side="top" returnTo="/dashboard" />
      {children}
    </>
  );
}

// Check in code
const { impersonator } = await withAuth();
if (impersonator) {
  console.log(`Admin ${impersonator.email} is impersonating this user`);
}
```

--------------------------------

### handleAuthkitProxy(request, authkitHeaders, options?)

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/middleware.md

A helper function to merge AuthKit headers into a NextResponse, supporting custom redirect configurations.

```APIDOC
## handleAuthkitProxy(request, authkitHeaders, options?)

### Description
Advanced helper for manually handling AuthKit internal headers in custom middleware or route handlers.

### Signature
`function handleAuthkitProxy(request: NextRequest, authkitHeaders: Headers, options?: HandleAuthkitHeadersOptions): NextResponse`

### Parameters
- **request** (NextRequest) - Required - Current request object
- **authkitHeaders** (Headers) - Required - Headers from AuthKit middleware
- **options** (HandleAuthkitHeadersOptions) - Optional - Response options
  - **redirect** (string | URL) - Optional - URL to redirect to (relative or absolute)
  - **redirectStatus** (302 | 303 | 307 | 308) - Optional - HTTP status code for redirect (Default: 307 for GET/HEAD, 303 for POST/PUT/DELETE)

### Returns
`NextResponse` with properly merged AuthKit headers.

### Example
```typescript
import { handleAuthkitProxy } from '@workos-inc/authkit-nextjs';

export async function middleware(request: NextRequest) {
  const authkitHeaders = new Headers();
  
  return handleAuthkitProxy(request, authkitHeaders, {
    redirect: '/authenticated',
    redirectStatus: 307
  });
}
```
```

--------------------------------

### Handle Authentication Callback

Source: https://github.com/workos/authkit/blob/main/_autodocs/README.md

Create the API route to handle the authentication callback and redirect users.

```typescript
// app/api/auth/callback/route.ts
import { handleAuth } from '@workos-inc/authkit-nextjs';

export const GET = handleAuth({
  returnPathname: '/dashboard'
});
```

--------------------------------

### Define SwitchToOrganizationOptions interface

Source: https://github.com/workos/authkit/blob/main/_autodocs/types.md

Defines configuration options for switching organizations, used by switchToOrganization() and useAuth().

```typescript
interface SwitchToOrganizationOptions {
  /** URL to redirect to after switching organizations. */
  returnTo?: string;
  /** Next.js revalidation strategy: 'none' | 'tag' | 'path'. */
  revalidationStrategy?: 'none' | 'tag' | 'path';
  /** Array of revalidation tags to clear from cache. */
  revalidationTags?: string[];
}
```

--------------------------------

### Apply Response Headers

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Applies partitioned headers to a NextResponse object.

```typescript
function applyResponseHeaders(
  response: NextResponse,
  responseHeaders: Headers
): NextResponse
```

--------------------------------

### getSignInUrl()

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/auth-functions.md

Generates a sign-in URL for redirecting users to the authentication flow.

```APIDOC
## getSignInUrl()

### Description
Generate a sign-in URL for redirecting users to the authentication flow.

### Signature
`function getSignInUrl(authUrlOptions?: GetSignUrlOptions): Promise<string>`

### Parameters
- **authUrlOptions** (GetSignUrlOptions) - Optional - Configuration options for the sign-in URL
  - **returnTo** (string) - Optional - URL to redirect to after successful sign-in
  - **organizationId** (string) - Optional - Organization ID to scope the sign-in to a specific organization
  - **redirectUri** (string) - Optional - Custom redirect URI (overrides default)
  - **loginHint** (string) - Optional - Pre-populate the login field with an email hint
  - **prompt** ('consent') - Optional - Force consent screen to be shown
  - **state** (string) - Optional - Custom state parameter for CSRF protection
  - **maxAge** (number) - Optional - Maximum allowable elapsed time in seconds since last authentication

### Returns
- **Promise<string>** - Resolves to the complete sign-in URL.

### Throws
- **AuthKitError** - If required environment variables are missing.
```

--------------------------------

### withAuth()

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/session-management.md

Retrieve the current user's session information with optional authentication enforcement.

```APIDOC
## withAuth(options)

### Description
Retrieve the current user's session information with optional authentication enforcement.

### Signature
`function withAuth(options?: { ensureSignedIn?: true | false }): Promise<UserInfo | NoUserInfo>`

### Parameters
- **options** (object) - Optional - Session options
  - **ensureSignedIn** (boolean) - Optional - When true, returns UserInfo (never NoUserInfo); when false or omitted, may return either type

### Returns
- When ensureSignedIn: true: Promise resolving to UserInfo with authenticated user data
- When ensureSignedIn: false (default): Promise resolving to UserInfo | NoUserInfo

### Throws
- AuthKitError if session decryption fails
```

--------------------------------

### workos.apiKeys.createApiKey

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Creates a new API key for an application.

```APIDOC
## workos.apiKeys.createApiKey

### Description
Creates a new API key with an optional expiration date.

### Parameters
- **name** (string) - Required - The name of the API key.
- **expiresAt** (string) - Optional - The expiration date for the key.
```

--------------------------------

### workos.userManagement.createUser

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Creates a new user in the WorkOS system.

```APIDOC
## workos.userManagement.createUser

### Description
Creates a new user with the provided credentials and profile information.

### Parameters
- **clientId** (string) - Required - The WorkOS client ID.
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.
- **firstName** (string) - Optional - The user's first name.
- **lastName** (string) - Optional - The user's last name.
```

--------------------------------

### Configure SSO Organization ID

Source: https://github.com/workos/authkit/blob/main/src/app/using-your-own-ui/README.md

Add the Organization ID to your local environment variables to enable Single Sign-On.

```bash
SSO_ENABLED_ORGANIZATION_ID="<your Organization ID>"
```

--------------------------------

### List Organizations with TypeScript

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Fetches a paginated list of organizations.

```typescript
const { data: orgs } = await workos.organizations.listOrganizations({
  limit: 10
});
```

--------------------------------

### Evaluate Feature Flags for a User

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Demonstrates how to evaluate flags by providing user and organization identifiers.

```typescript
import { getFeatureFlagsRuntimeClient } from '@workos-inc/authkit-nextjs';

const client = getFeatureFlagsRuntimeClient();

const flags = await client.evaluateFlags({
  userId: 'user_123',
  organizationId: 'org_456'
});

if (flags['new-dashboard']) {
  // Show new dashboard UI
}
```

--------------------------------

### applyResponseHeaders()

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Applies partitioned headers to a response object.

```APIDOC
## applyResponseHeaders(response, responseHeaders)

### Description
Applies partitioned headers to a response object.

### Parameters
- **response** (NextResponse) - Required - The response object to modify.
- **responseHeaders** (Headers) - Required - The headers to apply to the response.

### Returns
- **NextResponse** - The response object with applied headers.
```

--------------------------------

### List Users

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Fetch a paginated list of users associated with the client ID.

```typescript
const { data: users } = await workos.userManagement.listUsers({
  clientId: process.env.WORKOS_CLIENT_ID,
  limit: 10,
  before: 'cursor_123',  // Pagination
  after: 'cursor_456'
});
```

--------------------------------

### AuthKitProvider

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

The AuthKitProvider is a context provider component that must wrap your application to enable AuthKit functionality.

```APIDOC
## AuthKitProvider

### Description
Context provider component that wraps your application to enable AuthKit hooks and session management on the client.

### Props
- **children** (ReactNode) - Required - Child components that can use AuthKit hooks
- **onSessionExpired** (false | (() => void)) - Optional - Callback when session expires. Pass false to disable expiration checks. Default: reload page
- **initialAuth** (Omit<UserInfo | NoUserInfo, 'accessToken'>) - Optional - Initial auth state from server (skips initial client fetch if provided)

### Usage Example
```typescript
import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AuthKitProvider>
          {children}
        </AuthKitProvider>
      </body>
    </html>
  );
}
```
```

--------------------------------

### List Invitations

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Lists all invitations associated with a specific client ID.

```typescript
const { data: invitations } = await workos.userManagement.listInvitations({
  clientId: process.env.WORKOS_CLIENT_ID
});
```

--------------------------------

### authkitProxy(options)

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Configures the AuthKit middleware behavior for route protection and token management.

```APIDOC
## authkitProxy(options)

### Description
Configures the AuthKit middleware to handle route protection, OAuth redirects, and token refresh logic.

### Parameters
- **debug** (boolean) - Optional - Log middleware operations to console. Default: false.
- **middlewareAuth.enabled** (boolean) - Optional - Require authentication for protected routes. Default: false.
- **middlewareAuth.unauthenticatedPaths** (string[]) - Optional - Routes that don't require authentication. Default: [].
- **redirectUri** (string) - Optional - Custom OAuth redirect URI.
- **signUpPaths** (string[]) - Optional - Routes that hint at sign-up flow. Default: [].
- **eagerAuth** (boolean) - Optional - Proactively refresh tokens before expiry. Default: false.
- **refreshBufferSeconds** (number) - Optional - Seconds before token expiry to refresh. Default: 60.
```

--------------------------------

### partitionAuthkitHeaders()

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

Separates AuthKit internal headers from response headers, useful for custom middleware implementations.

```APIDOC
## partitionAuthkitHeaders(request, authkitHeaders)

### Description
Separates AuthKit internal headers from response headers. This is a low-level utility used for custom middleware that needs to handle AuthKit session headers manually.

### Parameters
- **request** (NextRequest) - Required - The incoming request object.
- **authkitHeaders** (Headers) - Required - The headers to be partitioned.

### Returns
- **AuthkitHeadersResult** (Object) - Contains `requestHeaders` (Headers for downstream requests) and `responseHeaders` (Headers for browser response).
```

--------------------------------

### workos.userManagement.createPasswordReset

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Initiates a password reset flow.

```APIDOC
## workos.userManagement.createPasswordReset

### Description
Sends a password reset email to the specified user.

### Parameters
- **clientId** (string) - Required - The WorkOS client ID.
- **email** (string) - Required - The email address of the user.
- **passwordResetUrl** (string) - Required - The URL for the password reset page.
```

--------------------------------

### workos.userManagement.listAuthFactors

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Lists authentication factors for a user.

```APIDOC
## workos.userManagement.listAuthFactors

### Description
Lists all authentication factors associated with a user.

### Parameters
- **userId** (string) - Required - The ID of the user.
```

--------------------------------

### workos.userManagement.authenticateWithMagicAuth

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Verifies a magic auth code to complete authentication.

```APIDOC
## workos.userManagement.authenticateWithMagicAuth

### Description
Verifies the magic auth code and returns session tokens.

### Parameters
- **clientId** (string) - Required - The WorkOS client ID.
- **code** (string) - Required - The verification code.
- **magicAuthId** (string) - Required - The ID of the magic auth request.
```

--------------------------------

### Server-Only Utility Functions

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/utility-functions.md

A list of functions that must be executed in a server-side context. Calling these from client components will result in errors.

```APIDOC
## Server-Only Functions

The following functions are restricted to server-side execution:

- `getSignInUrl()`
- `getSignUpUrl()`
- `signOut()`
- `switchToOrganization()`
- `withAuth()`
- `refreshSession()`
- `getTokenClaims()`
- `checkRecentAuth()`
- `saveSession()`
- `getSessionFromCookie()`
- `validateApiKey()`
- `getWorkOS()`
- `getFeatureFlagsRuntimeClient()`
```

--------------------------------

### Define GetAuthURLOptions interface

Source: https://github.com/workos/authkit/blob/main/_autodocs/types.md

Configuration options for generating authentication URLs, used by getSignInUrl() and getSignUpUrl().

```typescript
interface GetAuthURLOptions {
  /** Hint to show sign-up or sign-in screen. */
  screenHint?: 'sign-up' | 'sign-in';
  /** Path to return to after successful authentication. */
  returnPathname?: string;
  /** Organization ID to scope authentication to. */
  organizationId?: string;
  /** Custom redirect URI (overrides configured default). */
  redirectUri?: string;
  /** Pre-populate the login field with an email hint. */
  loginHint?: string;
  /** Force consent screen to be displayed. */
  prompt?: 'consent';
  /** Custom state value for OIDC state parameter. */
  state?: string;
  /** Maximum allowable elapsed time in seconds since last authentication (OIDC max_age). Requires @workos-inc/node >= 10.7.0. */
  maxAge?: number;
}
```

--------------------------------

### Implement AuthKit Middleware

Source: https://github.com/workos/authkit/blob/main/_autodocs/README.md

Protect routes by configuring the AuthKit proxy in your middleware file.

```typescript
// middleware.ts
import { authkitProxy } from '@workos-inc/authkit-nextjs';

export const middleware = authkitProxy({
  middlewareAuth: {
    enabled: true,
    unauthenticatedPaths: ['/sign-in', '/sign-up']
  }
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)']
};
```

--------------------------------

### Create Email/Password Sign-In Form

Source: https://github.com/workos/authkit/blob/main/_autodocs/integration-guide.md

A client-side form component that triggers the server action and manages loading states via useFormStatus.

```typescript
// app/sign-in/page.tsx
'use client';

import { useFormStatus } from 'react-dom';
import { handleEmailPasswordSignIn } from './actions';

export default function SignInForm() {
  const { pending } = useFormStatus();
  
  return (
    <form action={handleEmailPasswordSignIn}>
      <input
        type="email"
        name="email"
        placeholder="Email"
        required
      />
      <input
        type="password"
        name="password"
        placeholder="Password"
        required
      />
      <button disabled={pending}>
        {pending ? 'Signing in...' : 'Sign In'}
      </button>
    </form>
  );
}
```

--------------------------------

### workos.organizations.listOrganizations

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Lists organizations with optional pagination parameters.

```APIDOC
## workos.organizations.listOrganizations(options)

### Description
Returns a list of organizations.

### Parameters
- **options** (object) - Optional - Configuration object containing `limit` (number).
```

--------------------------------

### Create Organization Membership with TypeScript

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Adds a user to an organization with a specific role.

```typescript
const membership = await workos.organizationMemberships.createOrganizationMembership({
  organizationId: 'org_123',
  userId: 'user_456',
  roleId: 'member'  // or 'owner', 'admin'
});
```

--------------------------------

### workos.userManagement.authenticateWithCode

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Exchanges an OAuth/OIDC code for session tokens.

```APIDOC
## workos.userManagement.authenticateWithCode

### Description
Exchanges the authorization code for an access token.

### Parameters
- **clientId** (string) - Required - The WorkOS client ID.
- **code** (string) - Required - The authorization code.
- **redirectUri** (string) - Required - The callback URL.
```

--------------------------------

### useAccessToken()

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/components.md

A hook for managing access tokens with automatic refresh and freshness guarantees.

```APIDOC
## useAccessToken()

### Description
Hook for managing access tokens with automatic refresh and freshness guarantees.

### Signature
`function useAccessToken(): UseAccessTokenReturn`

### Returns
- **accessToken** (string | undefined) - Current access token (may be stale when tab inactive)
- **loading** (boolean) - Whether token is being fetched
- **error** (Error | null) - Last token operation error
- **refresh()** (function) - Manually trigger refresh
- **getAccessToken()** (function) - Get guaranteed fresh token (auto-refreshes if needed)
```

--------------------------------

### workos.userManagement.enrollAuthFactor

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Enrolls a new authentication factor.

```APIDOC
## workos.userManagement.enrollAuthFactor

### Description
Enrolls a new authentication factor for a user.

### Parameters
- **userId** (string) - Required - The ID of the user.
- **type** (string) - Required - The type of factor (e.g., 'totp').
```

--------------------------------

### Switch Organization Context

Source: https://github.com/workos/authkit/blob/main/_autodocs/configuration.md

Update the current organization context and retrieve updated user information.

```typescript
// Switch to specific organization
const userInfo = await switchToOrganization('org_123456', {
  returnTo: '/org-dashboard',
  revalidationStrategy: 'tag',
  revalidationTags: ['org-data']
});

// Access organization context
const { organizationId, role, roles } = userInfo;
```

--------------------------------

### Checking Permissions

Source: https://github.com/workos/authkit/blob/main/_autodocs/README.md

Verify if a user possesses specific permissions to authorize access to resources.

```typescript
const { permissions } = await withAuth();

if (permissions?.includes('admin:write')) {
  // User has permission
}
```

--------------------------------

### List Organization Memberships with TypeScript

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Fetches a paginated list of memberships for a specific organization.

```typescript
const { data: memberships } = await workos.organizationMemberships.listOrganizationMemberships({
  organizationId: 'org_123',
  limit: 10
});
```

--------------------------------

### workos.organizations.createOrganization

Source: https://github.com/workos/authkit/blob/main/_autodocs/api-reference/workos-sdk.md

Creates a new organization with the specified name and domain data.

```APIDOC
## workos.organizations.createOrganization(options)

### Description
Creates a new organization in WorkOS.

### Parameters
- **options** (object) - Required - Configuration object containing `name` (string) and `domainData` (array of objects).
```
Tokens:
Raw