Skip to main content
The switchToOrganization function allows users to switch their active session context to a different organization. This is useful for multi-tenant applications where users belong to multiple organizations.

​
Function signature

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

​
Parameters

​
organizationId
string
required
The ID of the organization to switch to. The user must be authorized to access this organization.
​
options
SwitchToOrganizationOptions
Optional configuration for the organization switch.

​
Returns

​
UserInfo
Promise<UserInfo>
Returns the updated user session information for the new organization context.

​
Behavior

When you call switchToOrganization:
  1. Session refresh - Refreshes the session with the new organization context
  2. Authorization check - Verifies the user has access to the target organization
  3. Cache revalidation - Invalidates Next.js cache according to the strategy
  4. Automatic redirect - Redirects to the specified page (unless strategy is 'none')
If the user is not authorized for the target organization, or if SSO/MFA is required, the function will redirect to AuthKit for re-authentication.

​
Examples

​
Basic organization switch

'use server';

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

export async function switchOrg(organizationId: string) {
  // Switches org, revalidates current page, and redirects
  await switchToOrganization(organizationId);
}

​
Switch with custom redirect

'use server';

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

export async function switchToOrgAndGoToDashboard(organizationId: string) {
  await switchToOrganization(organizationId, {
    returnTo: '/dashboard',
  });
}

​
Switch with tag-based revalidation

'use server';

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

export async function switchOrgRevalidateTags(organizationId: string) {
  await switchToOrganization(organizationId, {
    revalidationStrategy: 'tag',
    revalidationTags: ['user-data', 'org-settings', 'team-members'],
  });
}

​
Switch without automatic redirect

'use server';

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

export async function switchOrgWithoutRedirect(organizationId: string) {
  const userInfo = await switchToOrganization(organizationId, {
    revalidationStrategy: 'none',
  });
  
  // Handle the result manually
  console.log(`Switched to org: ${userInfo.organizationId}`);
  return userInfo;
}

​
Organization switcher component

'use client';

import { useTransition } from 'react';
import { switchToOrgAction } from './actions';

export function OrganizationSwitcher({ 
  organizations 
}: { 
  organizations: Array<{ id: string; name: string }> 
}) {
  const [isPending, startTransition] = useTransition();

  return (
    <select
      onChange={(e) => {
        startTransition(async () => {
          await switchToOrgAction(e.target.value);
        });
      }}
      disabled={isPending}
    >
      {organizations.map((org) => (
        <option key={org.id} value={org.id}>
          {org.name}
        </option>
      ))}
    </select>
  );
}

// actions.ts
'use server';

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

export async function switchToOrgAction(organizationId: string) {
  await switchToOrganization(organizationId);
}

​
Error handling

The function may throw errors in several scenarios:
If the user doesn’t have access to the target organization, they’ll be redirected to AuthKit for re-authentication.
If the organization requires SSO authentication, the user will be redirected to the SSO provider.
If MFA is required but not enrolled, the user will be redirected to complete MFA setup.

​
Use cases

Multi-tenant applications

Allow users to switch between different company workspaces or teams

Role-based access

Update user permissions when switching to organizations with different roles

Data isolation

Ensure users only see data from their active organization context

Billing contexts

Switch between organizations with different billing plans or limits

Build docs developers (and LLMs) love

Get started for freeTalk to us