useIdentities

useIdentities() lists the signed-in user’s connected identities (email, OAuth, SAML) and exposes helpers to start an OAuth link flow or unlink an existing identity. It tracks loading state and the in-flight unlinking id.

When to use it

• Build a “connected accounts” screen (the prebuilt <ConnectedAccounts> component wraps this).

Usage

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

function ConnectedAccounts() {
  const { identities, linkProvider, unlinkIdentity, unlinkingId } = useIdentities();

  return (
    <>
      <button onClick={() => linkProvider('google')}>Connect Google</button>
      <ul>
        {identities.map((i) => (
          <li key={i.id}>
            {i.label ?? i.issuer}
            <button disabled={unlinkingId === i.id} onClick={() => unlinkIdentity(i.id)}>
              Disconnect
            </button>
          </li>
        ))}
      </ul>
    </>
  );
}

Returns

Name	Type	Description
identities	LinkedIdentity[]	Connected identities. Empty while loading or when signed out. Each carries id, protocol ('email' | 'oidc' | 'saml'), issuer, label, status, createdAt, and subject (the account the identity points at: the email address for email identities, or the provider subject for oidc/saml; useful for labeling which account a row represents).
isLoading	boolean	true while identities are being fetched.
error	ToriiError | null	Structured error from the last operation (code, message, optional status/details), or null. Show error.message or branch on error.code.
refresh	() => Promise<void>	Re-fetch identities from the server.
linkProvider	(provider: string) => Promise<void>	Start the OAuth linking flow: redirects the browser to the provider on success. Lands back at afterOauthLinkPath.
unlinkIdentity	(identityId: string) => Promise<MutationResult<void>>	Unlink an identity by id. Resolves a MutationResult; check .ok (unlinking the last sign-in method fails).
unlinkingId	string | null	Id of the identity currently being unlinked, else null.

Notes

• linkProvider navigates away: it sends the browser to the provider’s authorize URL. After the IdP callback the user lands at afterOauthLinkPath (set on <ToriiProvider>, defaults to "/").
• Last identity is protected: unlinkIdentity resolves { ok: false } and sets error rather than removing the user’s only remaining sign-in method.

TypeScript

import type { UseIdentitiesReturn, LinkedIdentity } from '@torii-js/torii-react';