useOrganizations

useOrganizations() exposes the organizations the signed-in user belongs to, the currently-active organization (the JWT o.id claim), and the imperative helpers to create and switch organizations. It reads from the cached boot payload on <ToriiProvider>, so there’s no extra round-trip on render.

This is the data layer behind <OrganizationList>. Use it directly when you need a custom org surface (e.g. your own switcher in a navbar). For the full feature — roles, permissions, and dashboard setup — see Organizations & roles.

Usage

import { useOrganizations } from '@torii-js/torii-react';

function OrgSwitcher() {
  const { organizations, activeOrganizationId, switchActiveOrganization } = useOrganizations();

  return (
    <select
      value={activeOrganizationId ?? ''}
      onChange={(e) => switchActiveOrganization(e.target.value)}
    >
      {organizations.map((org) => (
        <option key={org.id} value={org.id}>
          {org.name}
        </option>
      ))}
    </select>
  );
}

Returns

Field	Type	Description
organizations	ClientOrganizationSummary[]	Orgs the user belongs to ({ id, name, role, role_name? }). role_name is the human-readable display name to show; fall back to role when it’s absent.
activeOrganizationId	string | null	The active org id from the JWT o.id claim, or null when none is active.
activeOrganization	ClientOrganizationSummary | null	The active org summary, or null.
createOrganization	(name: string) => Promise<ClientOrganizationSummary>	Creates an org and resolves to its summary. Rejects on failure.
getOrganization	(organizationId: string) => Promise<ClientOrganization>	Reads one org including its public_metadata. A real request: the cached organizations list omits metadata. Rejects on failure.
updateOrganization	(organizationId: string, patch: { name?: string; publicMetadata?: Record<string, unknown> }) => Promise<ClientOrganization>	Partial update, admin role only. name renames; publicMetadata is deep-merged server-side (a key set to null is removed). Sending an empty patch is a 400. Rejects on failure.
renameOrganization	(organizationId: string, name: string) => Promise<ClientOrganizationSummary>	Renames an org (admin only). Superseded by updateOrganization, which does the same and can patch metadata in the same request.
acceptInvitation	(token: string) => Promise<ClientOrganizationSummary>	Redeems an invitation token as the signed-in user (their verified email must match the invite) and resolves to the joined org summary. The org appears in organizations once the session refresh this triggers resolves. Rejects on failure.
switchActiveOrganization	(organizationId: string) => Promise<void>	Switches the active org: re-mints the access token with the new active org in the o claim and persists the choice server-side, so subsequent session refreshes retain it.
leaveOrganization	(organizationId: string) => Promise<void>	Leaves an org the user belongs to (self-removal). Resolves once the refreshed session no longer lists it. Rejects on failure, including the server’s refusal to let an organization’s last administrator leave: surface error.message rather than treating it as a no-op.

Behaviour

• Active org is derived from the JWT. When activeOrganizationId is null, no org is active, so prompt the user to pick one (e.g. render <OrganizationList>).
• switchActiveOrganization persists. The choice is stored on the session row, so a reload re-mints the token with the same active org.
• Metadata is not on the cached list. organizations is read from the session payload the provider already has, and that payload deliberately carries no metadata so a cold load stays small. Use getOrganization when you need public_metadata. See Organizations & roles for the merge semantics and the private_metadata boundary.
• A metadata-only updateOrganization skips the session refresh. Only a rename changes what the cached list holds, so a metadata patch avoids the extra round-trip.
• Must be called inside a <ToriiProvider>.