useAuth

useAuth() is the primary hook for reading authentication state. It returns the signed-in flags, the current user and userProfile, the user’s organizations, and the imperative helpers you need to attach a token to a backend call or sign the user out. For switching the active org or managing memberships, use useOrganizations().

This is Torii’s curated public auth surface, deliberately kept to the small, familiar shape auth SDKs expose. The provider’s context carries more fields that the SDK’s own components read internally; those are not part of this hook.

When to use it

• Gate UI on isSignedIn (or use <SignedIn> / <SignedOut>).
• Read the current user / userProfile for display.
• Get a bearer token for your own backend calls (getToken(), async, refreshes near expiry).
• Sign the user out, or re-fetch the session after a gate completes.

Usage

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

function Account() {
  const { isLoaded, isSignedIn, userProfile, getToken, signOut } = useAuth();

  if (!isLoaded) return null;
  if (!isSignedIn) return <a href="/sign-in">Sign in</a>;

  async function callApi() {
    const token = await getToken();
    await fetch('/api/me', { headers: { Authorization: `Bearer ${token}` } });
  }

  return (
    <>
      <span>{userProfile?.name ?? userProfile?.email}</span>
      <button onClick={callApi}>Load</button>
      <button onClick={() => signOut()}>Sign out</button>
    </>
  );
}

Returns

useAuth() throws if called outside a <ToriiProvider>.

Name	Type	Description
isLoaded	boolean	true once the initial session probe has settled. Render gates should wait for this before trusting isSignedIn.
isLoading	boolean	true while the initial session probe is in flight.
isSignedIn	boolean	true when the user has an active session with no pending gates.
user	User | null	Identity decoded from the JWT (id, environmentId, emailVerified), or null when signed out. For full fields use userProfile.
userProfile	UserProfileData | null	Full profile from /me: email, name, locale, etc. null until the boot probe resolves.
organizations	ClientOrganizationSummary[]	Organizations the user belongs to in this environment ({ id, name, role, role_name? }); empty when signed out or with no memberships. Use useOrganizations() to switch the active org or manage members.
require	(params: { role } | { permission }) => boolean	Role/permission authorization check. true when the active-organization session satisfies the check, e.g. require({ role: 'org:admin' }). false with no active org. System permissions (org:sys_*) aren’t in the token, so check the role instead. Declarative form: <Show when={…}>.
getToken	(options?: { template?: string }) => Promise<string | null>	Async. Returns a usable access token, refreshing first if the current one is missing or within ~30s of expiry. Pass { template } to mint a one-off token from a named JWT template for a third-party service (Hasura, Supabase, …); that token is returned to you, not stored as the session token. Resolves null if the session ended (or the named template doesn’t exist). Prefer this when attaching a bearer token to your own requests.
getAccessToken	() => string | null	Sync. Reads the current access token as-is, with no refresh. Returns null when signed out. Use when you need the token synchronously and can tolerate a near-expiry value.
signIn	(tokens: AuthTokens) => void	Apply tokens from a successful sign-in / sign-up response. Flips session state in-page.
signOut	() => Promise<void>	Revoke the session server-side and clear local tokens.
refreshSession	() => Promise<void>	Re-fetch /me and update userProfile + session gates. Call after any action that may clear a session gate.
currentLanguage	string	The active language code.
setLanguage	(code: string) => void	Switch to a different configured language.
runtimeIncompatible	boolean	true once the server reports this SDK build is too old for an endpoint and the page must reload. Read it to render your own refresh prompt (<ToriiProvider> shows one automatically).

Notes

• getToken() vs getAccessToken(): getToken() is the one to reach for when calling your backend: it refreshes a near-expiry token before handing it back. getAccessToken() is synchronous and never refreshes. For most authed requests, prefer the useAuthFetch() hook, which attaches the bearer and retries on 401 for you.
• Template tokens: getToken({ template: 'hasura' }) mints a one-off token from a named JWT template for a third-party service. It is returned to you (not stored as the session token); resolves null if no such template exists. See JWT templates.
• Sign-out routing: drive post-sign-out navigation off isSignedIn flipping to false, or events.onSessionExpired on <ToriiProvider>.

TypeScript

import type {
  AuthContextValue,
  User,
  UserProfileData,
  ClientOrganizationSummary,
  AuthTokens,
} from '@torii-js/torii-react';