`useOrganizationList()` hook

useOrganizationList() is the broad organization-management hook built on top of useOrganizationMemberships(). It derives the organization list from the current user’s memberships, then layers the organization-level management actions on top of that list: members, invitations, domains, roles, enterprise connections, SCIM tokens, and organization creation or deletion.

Usage

The following example shows a basic usage of useOrganizationList().

export default function OrganizationPicker() {  const { organizations, loading } = useOrganizationList();  if (loading) {    return <p>Loading organizations…</p>;  }  return (    <ul>      {organizations?.map((organization) => (        <li key={organization.id}>{organization.name}</li>      ))}    </ul>  );}

Return value

The hook returns the following fields and methods.

›

organizations: Organization[] | undefined;

Organizations derived from the current user’s organization memberships.

›

[].id?: string | undefined;

Organization identifier.

›

[].name?: string | undefined;

Organization name.

›

[].image_url?: string | undefined;

Organization image URL.

›

[].description?: string | undefined;

Organization description.

›

[].member_count?: number | undefined;

Organization member count.

›

[].enforce_mfa?: boolean | undefined;

Whether the organization enforces MFA.

›

[].enable_ip_restriction?: boolean | undefined;

Whether the organization uses IP restrictions.

›

[].whitelisted_ips?: string[] | undefined;

Whitelisted IP addresses for the organization.

›

[].auto_assigned_workspace_id?: string | undefined;

Workspace automatically assigned for new members when configured.

›

loading: boolean;

Whether the organization memberships query is still loading.

›

error: null;

This hook currently hardcodes `null` instead of exposing the underlying membership-query error.

›

refetch: () => Promise<void>;

Revalidates the underlying organization memberships query.

›

createOrganization: (organization: NewOrgnization) => Promise<ApiResult<{ organization: Organization; membership: OrganizationMembership }>>;

Creates a new organization and refreshes both the organization list and the current session.

›

organization.name?: string | undefined;

Organization name.

›

organization.description?: string | undefined | undefined;

Optional organization description.

›

organization.image?: File | undefined | undefined;

Optional organization image.

›

updateOrganization: (organization: Organization, update: OrganizationUpdate) => Promise<ApiResult<Organization>>;

Updates one organization and refreshes the membership-derived list.

›

deleteOrganization: (organization: Organization) => Promise<void>;

Deletes an organization, clears token cache, and refreshes both the list and the current session.

›

leaveOrganization: (organization: Organization) => Promise<void>;

Leaves an organization as the current user.

›

getOrganizationMembers: (organization: Organization, params?: { page: number; limit: number; search?: string }) => Promise<PaginatedResponse<OrganizationMembership[]>>;

Loads organization members, optionally with pagination and search.

›

removeOrganizationMember: (organization: Organization, member: OrganizationMembership) => Promise<void>;

Removes one member from an organization.

›

getOrganizationRoles: (organization: Organization) => Promise<OrganizationRole[]>;

Loads the role definitions for an organization.

›

addRole: (organization: Organization, newRole: RoleCreate) => Promise<ApiResult<OrganizationRole>>;

Creates a custom organization role.

›

removeOrganizationRoles: (organization: Organization, role: OrganizationRole) => Promise<void>;

Removes one organization role.

›

addRoleToOrganizationMember: (organization: Organization, member: OrganizationMembership, role: OrganizationRole) => Promise<OrganizationMembership>;

Adds a role to a specific organization member.

›

removeRoleFromOrganizationMember: (organization: Organization, member: OrganizationMembership, role: OrganizationRole) => Promise<OrganizationMembership>;

Removes a role from a specific organization member.

›

getOrganizationInvitations: (organization: Organization) => Promise<OrganizationInvitation[]>;

Loads pending invitations for an organization.

›

inviteOrganizationMember: (organization: Organization, invitation: OrganizationInvitationPayload) => Promise<OrganizationInvitation>;

Invites a user into an organization, optionally into a workspace with a workspace role.

›

discardOrganizationInvitation: (organization: Organization, invitation: OrganizationInvitation) => Promise<OrganizationInvitation>;

Discards a pending organization invitation.

›

resendOrganizationInvitation: (organization: Organization, invitation: OrganizationInvitation) => Promise<OrganizationInvitation>;

Resends a pending organization invitation.

›

getOrganizationDomains: (organization: Organization) => Promise<OrganizationDomain[]>;

Loads verified and unverified organization domains.

›

addOrganizationDomain: (organization: Organization, domain: NewDomain) => Promise<ApiResult<OrganizationDomain>>;

Adds a new domain to an organization.

›

verifyOrganizationDomain: (organization: Organization, domain: OrganizationDomain) => Promise<ApiResult<OrganizationDomain>>;

Verifies one organization domain.

›

removeOrganizationDomain: (organization: Organization, domain: OrganizationDomain) => Promise<ApiResult<OrganizationDomain>>;

Removes one organization domain.

›

getEnterpriseConnections: (organization: Organization) => Promise<EnterpriseConnection[]>;

Loads enterprise SSO connections for an organization.

›

createEnterpriseConnection: (organization: Organization, payload: CreateEnterpriseConnectionPayload) => Promise<EnterpriseConnection>;

Creates a new enterprise SSO connection.

›

updateEnterpriseConnection: (organization: Organization, connectionId: string, payload: UpdateEnterpriseConnectionPayload) => Promise<EnterpriseConnection>;

Updates an existing enterprise SSO connection.

›

deleteEnterpriseConnection: (organization: Organization, connectionId: string) => Promise<void>;

Deletes an enterprise SSO connection.

›

testEnterpriseConnectionConfig: (organization: Organization, payload: { protocol: 'saml' | 'oidc'; idp_entity_id?: string; idp_sso_url?: string; idp_certificate?: string; oidc_issuer_url?: string; oidc_client_id?: string; oidc_client_secret?: string }) => Promise<{ success: boolean; protocol: string; checks: Record<string, boolean>; errors?: Record<string, string> }>;

Tests an enterprise-connection configuration before it is saved.

›

testEnterpriseConnection: (organization: Organization, connectionId: string) => Promise<{ success: boolean; protocol: string; checks: Record<string, boolean>; errors?: Record<string, string> }>;

Tests an existing enterprise connection.

›

generateSCIMToken: (organization: Organization, connectionId: string) => Promise<SCIMTokenInfo>;

Generates a SCIM token for one enterprise connection.

›

getSCIMToken: (organization: Organization, connectionId: string) => Promise<SCIMTokenInfo>;

Loads the current SCIM token information.

›

revokeSCIMToken: (organization: Organization, connectionId: string) => Promise<void>;

Revokes the SCIM token for one enterprise connection.

How it works

This hook does not fetch a dedicated organization list endpoint. It derives organizations from useOrganizationMemberships(), so the list only contains organizations the current user is actually a member of.

The management methods are organization-scoped helpers layered on top of that membership-derived list. That is why most methods take an organization object as their first argument.

The hook mixes read helpers and mutation helpers. It is useful for admin or management UI, but it is broader than the hooks you want for a simple picker or active-scope display.

Creation and deletion clear token or session-adjacent state and refetch shared queries because those actions can change the user’s active scope and available memberships.

The current implementation hardcodes error: null instead of exposing the underlying membership query error. The docs reflect that behavior as it exists today.

When to use it

Examples

Render the organization list

export default function OrganizationList() {  const { organizations, loading } = useOrganizationList();  if (loading) {    return <p>Loading organizations…</p>;  }  return (    <ul>      {organizations?.map((organization) => (        <li key={organization.id}>{organization.name}</li>      ))}    </ul>  );}

Create a new organization

export default function CreateOrgButton() {  const { createOrganization } = useOrganizationList();  async function create() {    await createOrganization({      name: 'Acme',      description: 'Customer-facing workspace',    });  }  return <button onClick={create}>Create organization</button>;}

Load organization members

export default function LoadMembers() {  const { organizations, getOrganizationMembers } = useOrganizationList();  async function load() {    const organization = organizations?.[0];    if (!organization) {      return;    }    const result = await getOrganizationMembers(organization, {      page: 1,      limit: 20,    });    console.log(result.items);  }  return <button onClick={load}>Load members</button>;}

useOrganizationList() hook