Creates a new authentication client bound to a Faable Auth tenant.
The constructor kicks off FaableAuthClient.initialize in the background; you do not need to await anything before calling other methods. Prefer the createClient factory in app code — it has the same effect with less ceremony.
Tenant settings. domain and clientId are required and
throw synchronously when missing.
OptionalaudienceOptionalscopeCached session value last persisted by the client.
This is a synchronous accessor that returns whatever the client has already loaded into memory. It can lag behind storage (for example, across tabs before the broadcast event arrives) and never triggers a refresh. Prefer FaableAuthClient.getSession when you need an authoritative value, especially on the server.
The cached Session or null if no user is signed in.
The result of the most recent FaableAuthClient.initialize run, or
null while the first one is still in flight.
The constructor starts initialize() in the background and discards the
promise; this accessor lets code that cannot await it (for example a
React provider effect) read whether the last OAuth/redirect attempt
errored, instead of being stuck with a session that silently stays
null.
Returns the login method the user last completed on this browser, or
null when none was recorded — for login UIs that want to show a
PostHog-style "Last used" hint next to the matching sign-in button.
A method is recorded only when the login actually establishes a session
(the OAuth/password redirect round-trip finishing, or an OTP exchange
succeeding); a clicked button whose flow was abandoned or failed leaves
no trace. The record survives FaableAuthClient.signOut on
purpose and lives in a dedicated cookie, so it can be shared across
subdomains via the lastUsedCookie.domain client config.
The last confirmed method (oauth logins carry the
connection / connection_id they were started with) or null.
Links an additional OAuth identity (e.g. GitHub) to the CURRENTLY signed-in user — the identity round-trip proves control of the provider account and attaches it to the session user; it never signs in, never creates a user, and never touches the user's email or profile.
This is NOT signInWithOauthConnection: a sign-in with an unknown
provider identity creates a brand-new user, which is exactly the
duplicate-account hole "connect" buttons used to fall into. Requires an
active session (the server returns error=login_required otherwise) and
must not be combined with prompt: 'login' (it would destroy the
session being linked to).
On failure the server redirects back with ?error=... — read it with
getRedirectError after the round-trip.
Finishes a sign-in that a second-factor policy interrupted.
Call it with the mfa_token from an AuthMfaRequiredError and the
code the user typed — six digits from their authenticator app, or one of
their recovery codes.
A wrong code does NOT consume the token: prompt again with the same one instead of restarting the sign-in. The token does expire (a few minutes), after which the flow has to start over.
Optionalaudience?: stringOptionaltype?: "otp" | "recovery_code"Defaults to otp — the authenticator app.
Starts an OAuth / social login by redirecting the browser to the tenant's
/authorize endpoint for the chosen connection.
In browsers the SDK redirects the current window unless
skipBrowserRedirect is true. On that redirect success path the returned
promise never resolves — the pending navigation owns the page, so a
loading state you tie to the await stays on until unload instead of
flashing back. Pass skipBrowserRedirect: true to get { data: { url } }
back and drive the navigation yourself. PKCE is used by default in
browsers, falling back to the implicit flow elsewhere. Prefer
connection_id when known — the backend resolves it without an extra
lookup; connection (by name) is kept for legacy tenants.
// Redirects the current window; the promise does not resolve on success.
await auth.signInWithOauthConnection({
connection: 'google',
redirectTo: 'https://app.example.com/callback'
})
// Or take over the navigation yourself:
const { data } = await auth.signInWithOauthConnection({
connection: 'google',
skipBrowserRedirect: true
})
window.location.assign(data.url)
Completes a passwordless login by exchanging an OTP code for a session.
Pair this with FaableAuthClient.signInWithPasswordless called
with type: 'code'. On success the new session is persisted to storage
and a SIGNED_IN event is broadcast.
The user identifier and the OTP code they received.
Starts a passwordless login flow by emailing the user either an OTP code or a magic link.
type: 'code' sends a short code the user pastes into your UI; finish
the flow with FaableAuthClient.signInWithOtp.type: 'link' sends a clickable link that lands on your redirectUri
with the tokens already attached, processed by
FaableAuthClient.initialize on page load.The user's email and the delivery mechanism.
Signs the user in with a username + password against a database connection on the tenant.
The server responds with an HTML form that posts the user back to the
tenant's /login/callback to complete the OAuth flow; the SDK
auto-submits it from the current document. That is why the success path
resolves to { data: null, error: null } — the actual session lands on
the redirect target, not on this return value. Subscribe with
FaableAuthClient.onAuthStateChange to observe the resulting
SIGNED_IN event.
Registers a new user against the tenant's database connection with an email + password, then signs them in — so an email/password signup form can live entirely in the browser with no backend of your own.
This calls the public POST /dbconnections/signup endpoint (the Faable
analogue of Auth0's /dbconnections/signup) which creates the user and
its credential in one step, then chains
FaableAuthClient.signInWithUsernamePassword to establish the
session.
Auto-login navigates the browser. Like every interactive
username/password login in this SDK, the sign-in step submits a form that
round-trips through the auth server, so on success the page redirects to
your redirectTo and the live session is delivered there by
FaableAuthClient.initialize (and a SIGNED_IN event). This method
only returns synchronously when signup itself fails, or in non-navigating
runtimes (e.g. tests).
The user is created with email_verified: false; any verification /
welcome email is driven by the tenant's account settings.
The new user's email, password and optional profile fields.
const { error } = await auth.signUp({
email: 'user@example.com',
password: '••••••••',
name: 'Ada Lovelace',
redirectTo: 'https://app.example.com/callback'
})
if (error) showError(error.message) // e.g. 'email_taken', 'signup_disabled'
// otherwise the browser is already navigating to complete the login
Redirects the current window to the tenant's /authorize endpoint.
Fire-and-forget: there is no return value because the browser navigates
away. The session lands back on your redirectUri, where
FaableAuthClient.initialize consumes it on the next page load.
Optionalacr_values?: string | string[]Optionalaudience?: stringOptionalqueryParams?: { [key: string]: string }OptionalredirectTo?: stringOptionalscope?: stringBuilds the tenant's /authorize URL without redirecting the browser.
Useful when you need to render a login link, open the page in a popup, or hand the URL to a different runtime (e.g. a webview). For the everyday "click → redirect" flow use FaableAuthClient.authorize or FaableAuthClient.signInWithOauthConnection.
The redirect target is resolved with this precedence:
options.redirectTo → config.redirectUri → window.location.origin.
Optionalacr_values?: string | string[]OIDC acr_values — the assurance level this request demands.
urn:faable:loa:2 asks for a login that satisfied a second factor,
even when the tenant's policy would not have required one. Combine
with prompt: 'login' to force a fresh step-up rather than reusing an
existing single-factor session.
Optionalaudience?: stringOptionalconnection?: stringOptionalqueryParams?: { [key: string]: string }Extra /authorize params merged in as-is — e.g.
{ prompt: 'select_account' } or { prompt: 'login' } to force
account selection / re-authentication even when an SSO session exists.
OptionalredirectTo?: stringOptionalresponse_type?: stringOptionalscope?: stringThe fully-qualified authorize URL.
Builds the tenant's RP-initiated logout URL
({domain}/logout?client_id=…).
Navigate the browser to it (top-level, not fetch) to end the session and
clear the auth server's SSO cookie — the only reliable way to do that from
another origin. FaableAuthClient.signOut does this for you by
default; use this helper when you want to drive the navigation yourself.
OptionalreturnTo?: stringWhere to send the browser after logout, mapped to
the OIDC post_logout_redirect_uri. Must be registered as a logout URL
on the client or the server responds 400.
Sends the user through a fresh login that must satisfy a second factor, regardless of the tenant's policy or of an existing single-factor session.
The pattern for a sensitive action — changing payment details, deleting an
organisation — where the application wants a stronger proof than the one
the session already carries. Read FaableAuthClient.getAal first:
a session that is already 2 needs no step-up.
The claims of the current session's access token, decoded locally — the
standard JWT set plus any custom claim the tenant put there (a
connection's claims_mapping, an Action's
api.accessToken.setCustomClaim). Refreshes the session first when it
has expired, exactly like getSession, so the claims are always
those of a live token; custom claims survive refreshes by design.
claims is null (with no error) when there is no session. The token
is decoded, not signature-verified: use the result for UI and routing
decisions, never as authorization — that is the resource server's job.
Narrow your own claims with the generic parameter.
Error the auth server returned via redirect on the current page load
(?error=access_denied&error_description=..., RFC 6749 §4.1.2.1), or
null when the page wasn't reached through a failed auth round-trip.
Consume-once: the first read clears it (and the params were already stripped from the URL at initialization), so a later router navigation can't re-show a stale failure. Exists because the promise returned by signInWithOauthConnection dies with the top-level navigation — this is the only place the app can learn WHY the round-trip failed (e.g. an action deny like "Signups from this network are currently restricted").
Returns the session, refreshing it if necessary.
The session returned can be null if no user is signed in or the last
one has logged out.
IMPORTANT: This method loads values directly from the storage
attached to the client. If that storage is based on request cookies (for
example, on the server) the values in it may not be authentic and
therefore it's strongly advised against using this method and its
results in such circumstances — a warning will be emitted when the
storage exposes isServer: true. Re-fetch the user with a verified
call (or verify the access token yourself) before trusting it.
Why the SDK last terminated the session on its own (a refresh rejected
by the server — e.g. code: 'user_suspended', a revoked grant), or
null when the last sign-out was voluntary or there was none.
Consume-once, like getRedirectError: the first read clears it so a later visit to the login page can't re-show a stale banner. Persisted in storage (not memory) because the terminating tab usually navigates away — the login page that renders the reason is a fresh document.
Subscribes to auth-state changes for this client.
The callback fires for INITIAL_SESSION once shortly after subscribing
(so consumers don't have to special-case "no event yet"), and then for
every SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, PASSWORD_RECOVERY,
and USER_UPDATED event. Events are broadcast across tabs through
BroadcastChannel, so a sign-in or sign-out in one tab reaches every
other tab using the same storageKey.
Invoked with the event name and the new session (or
null on SIGNED_OUT). Can return a promise — the SDK awaits it.
{ data: { subscription } } — call subscription.unsubscribe()
to stop listening.
Forces a new session by exchanging a refresh token regardless of expiry.
Normally the SDK handles refresh transparently via the auto-refresh
ticker; call this only when you need to force an immediate refresh —
e.g. right after a server-side action that changed the user's claims.
Omit currentSession to reuse whatever FaableAuthClient.getSession
returns.
OptionalcurrentSession: { refresh_token: string }Optional session shape carrying the refresh token
to exchange. When passed it must include refresh_token.
Adopts an externally-provided session into the client.
Decodes the access token to find its expiry; refreshes immediately when
already expired, otherwise fetches the user info to round-trip the
session. Persists the result and broadcasts SIGNED_IN. An invalid
refresh or access token surfaces as error on the returned object.
Minimal session shape — an access token and a refresh token. Other fields are recomputed.
Starts an auto-refresh process in the background. The session is checked every few seconds. Close to the time of expiration a process is started to refresh the session. If refreshing fails it will be retried for as long as necessary.
If autoRefreshToken is enabled in the client config you don't need to
call this function, it will be called for you.
On browsers the refresh process works only when the tab/window is in the foreground to conserve resources as well as prevent race conditions and flooding auth with requests. If you call this method any managed visibility change callback will be removed and you must manage visibility changes on your own.
On non-browser platforms the refresh process works continuously in the background, which may not be desirable. You should hook into your platform's foreground indication mechanism and call these methods appropriately to conserve resources.
Starts a verified email change for the currently signed-in user.
The user must be authenticated — the call is made with the session's
access token, and the auth server only lets a user change their own
email. It creates a verification ticket and emails the user; the change
is applied only after they click the link, which the server handles and
then redirects to redirect_uri. The current session is unaffected until
then.
The new email plus optional verification policy.
verification_mode: 'new_only' verifies just the new address;
'old_and_new' also requires confirming from the old one. When
omitted the account's default policy applies.redirect_uri: where the server sends the user after they verify.Triggers a "change your password" email for a database-connection user.
The current session is unaffected — the user clicks the link in the email and completes the reset on the tenant's hosted pages. The promise resolves once the email has been queued.
The user's email address.
Signs the user out and clears the session from storage.
In a browser context this removes the persisted session and broadcasts a
SIGNED_OUT event to every tab listening on the same storageKey. The
access token JWT itself remains valid until its exp — keep that
expiry short.
By default (global scope, in a browser) this navigates the page to the
auth server's /logout to also clear the SSO cookie, then returns to
returnTo if given. Without that navigation the SSO session survives on
the auth domain and the next /authorize silently re-logs the previous
user — a cross-origin fetch cannot clear that cookie. On this path the
returned promise does not resolve (the browser is unloading). Pass
{ redirect: false } to keep the legacy fetch-only behaviour, or use
FaableAuthClient.getLogoutUrl to drive the navigation yourself.
Scopes:
'global' (default) — invalidate all refresh tokens for the user and,
in a browser, redirect to /logout to clear the SSO cookie'local' — only clear this client's storage (no redirect)'others' — invalidate every refresh token except this device's; no
SIGNED_OUT event is fired locally (no redirect)await auth.signOut() // global — clears local + auth SSO cookie via redirect
await auth.signOut({ returnTo: 'https://app.example.com/bye' }) // + landing
await auth.signOut({ redirect: false }) // legacy: local + best-effort fetch
await auth.signOut({ scope: 'local' }) // only this device, no redirect
Completes an OAuth / magic-link / password-recovery redirect on your callback route and reports the outcome.
The SDK already consumes the URL during the initialize() it kicks off
from the constructor; this is a thin, discoverable wrapper that awaits
that same in-flight run (idempotent) so you can:
error instead of hanging on a "Signing you in…" screen when
the exchange fails (e.g. an expired PKCE verifier).It also returns returnTo — the app-side destination you optionally
passed to signInWith*({ returnTo }) — so you don't need a side channel
(like sessionStorage) to remember where to send the user.
Initializes the client session either from the URL or from storage.
Automatically called once from the constructor and idempotent — extra calls return the same in-flight promise. Call it explicitly when you need to await an OAuth, magic link, or password-recovery redirect to finish processing so you can surface any returned error.
A promise that resolves to { error } — non-null when the URL
carried a failure or storage was corrupt; never throws.
Authenticator Assurance Level of the current session: 2 when it
satisfied a second factor (or a passkey that verified the user did both
at once), 1 for a single factor, 0 when there is no session.
Read locally from the access token's acr claim — no network call — so it
is cheap enough to gate a render on.
Did the current session authenticate with this method?
Values follow RFC 8176 as the server emits them: pwd, otp, hwk for
a hardware key, federated for a social login, and mfa once a second
factor was satisfied.
The main entry point of the SDK: an isomorphic client bound to a Faable Auth tenant that drives every authentication flow.
Prefer creating it through the createClient factory in app code. Once instantiated it begins loading its session in the background, so you can subscribe to auth-state and trigger sign-ins right away. The most common starting points are the sign-in methods and getSession.
See
Get Started with Faable Auth