useOrganizationInvitations

useOrganizationInvitations() is the headless data layer behind <OrganizationProfile>’s Invitations tab. Use it to build a custom invitation surface: it lists the pending invitations, creates new ones (returning a share-link token), and revokes them.

All three operations are admin-gated server-side, so a non-admin caller’s requests fail with a forbidden error. invite always resolves to a ClientInvitation carrying the raw share-link token. If the environment configures an invitation accept URL (dashboard → Organizations settings), Torii also emails the invitee a link to that URL with the ticket appended — best-effort and additive, so the share link always works regardless. Invitation creation is rate-limited to 50 per hour per organization; past that invite rejects with a 429 (organization_invitation_rate_limited) — contact [email protected] to raise it.

Usage

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

function Invites({ orgId }: { orgId: string }) {
  const { invitations, invite, revoke, lastInvite } = useOrganizationInvitations(orgId);

  return (
    <>
      <button onClick={() => invite('[email protected]', 'org:member')}>Invite</button>
      {lastInvite && <ShareLink token={lastInvite.token} />}
      <ul>
        {invitations.map((inv) => (
          <li key={inv.id}>
            {inv.email}
            <button onClick={() => revoke(inv.id)}>Revoke</button>
          </li>
        ))}
      </ul>
    </>
  );
}

Parameters

Param	Type	Description
organizationId	string	Org to manage. Defaults to the active org.
options.enabled	boolean	Whether to fetch the list. Default true. Pass false for a non-admin view so no forbidden error flashes; invite / revoke still work when called explicitly.

Returns

Field	Type	Description
invitations	PendingInvitation[]	Pending invitations ({ id, email, role, role_name?, created_at, expires_at }).
loading	boolean	A list fetch is in flight.
error	Error | null	Last error from the pending-list fetch, or null. invite/revoke failures reject instead of setting this.
lastInvite	ClientInvitation | null	The most recently created invitation (carries the share-link token), or null.
invite	(email: string, role: string) => Promise<ClientInvitation>	Create an invitation; resolves to its summary (with token). Rejects on failure.
revoke	(invitationId: string) => Promise<void>	Revoke a pending invitation. Rejects on failure.
refresh	() => void	Re-fetch the pending list.

Behaviour

• Must be called inside a <ToriiProvider>.
• invite refreshes the list on success; revoke removes the row from the list on success (it rejects on failure, leaving the list unchanged).
• error reflects only the pending-list fetch. invite/revoke failures reject instead — handle them at the call site.