AuthClient
Defined in: src/client/auth-client.ts:351
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AuthClient(
options?):AuthClient
Defined in: src/client/auth-client.ts:388
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”AuthClient
Methods
Section titled “Methods”dispose()
Section titled “dispose()”dispose():
void
Defined in: src/client/auth-client.ts:673
Releases what this client hooked: the browser listeners, the state subscription, and the refresh the identity has scheduled. Call it when discarding a client, so nothing it registered outlives it.
Returns
Section titled “Returns”void
getIdentity()
Section titled “getIdentity()”getIdentity():
Promise<Identity>
Defined in: src/client/auth-client.ts:534
Returns the current identity, restoring a previous session if available.
Returns
Section titled “Returns”Promise<Identity>
getPrincipal()
Section titled “getPrincipal()”getPrincipal():
Principal|undefined
Defined in: src/client/auth-client.ts:595
Who this origin can act as, or undefined where it cannot act.
The same question isAuthenticated answers, returning who rather than
whether — so the two never disagree. Synchronous, and read from the state
rather than from whatever material happens to be held, so a page renders on
it without opening a store and without waiting for a mint. That is the
difference from (await getIdentity()).getPrincipal(), which is asynchronous
and, on a load with no delegation worth adopting, waits for one to be minted.
A principal here means calls made as it will be accepted, so an expired
record answers undefined even though it still names an account, and so does
a record naming an account this origin holds nothing for. Returning one
anyway would have an application acting on a session that has ended: the
check most reach for is if (getPrincipal()), and it has to mean what it
looks like it means.
getStatus is where those cases are readable, and it carries the account principal in each of them — so nothing is lost by this being narrow, and an application wanting to say whose session ended asks there.
Returns
Section titled “Returns”Principal | undefined
getStatus()
Section titled “getStatus()”getStatus():
SessionStatus
Defined in: src/client/auth-client.ts:605
Who is signed in for this origin right now.
Synchronous, so a page can render on it without opening a store.
Returns
Section titled “Returns”isAuthenticated()
Section titled “isAuthenticated()”isAuthenticated():
boolean
Defined in: src/client/auth-client.ts:570
Checks whether the user has an active, non-expired session.
Returns
Section titled “Returns”boolean
memoize()
Section titled “memoize()”Call Signature
Section titled “Call Signature”memoize<
T>(produce):Promise<T>
Defined in: src/client/auth-client.ts:1159
Runs and journals a piece of your own async work so its result stays stable
across the 'redirect' flow.
In 'redirect' mode the page unloads on each step and signIn /
requestAttributes re-run on the return load, so a value you compute on the
first visit (from location, a fetch, crypto, …) would otherwise be
recomputed — and may differ — on the return. Wrap it in memoize: it runs
produce once on the first visit, journals the result, and replays that
result on the return load instead of re-running. Use it for a value the
post-flow code depends on, e.g. the URL to navigate to once sign-in
completes:
const next = await authClient.memoize( () => new URLSearchParams(location.search).get('next') ?? '/',);await authClient.signIn();location.assign(next); // the value captured before the redirectCall memoize in a stable order relative to signIn / requestAttributes
across loads (same order every load — branch only on values recovered from
earlier results), and keep the result JSON-serializable, since the journal
is JSON.
In 'window' mode there is no redirect, so this simply runs produce and
returns its result without persisting anything.
Mirrors the producer’s shape: a synchronous produce returns its value
directly, an asynchronous one returns a promise. Awaiting the result is
always safe (await on a non-promise is a no-op); the synchronous form lets
a value be memoized where an await is not possible, such as in a
constructor.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”produce
Section titled “produce”() => Promise<T>
Produces the value to journal on the first load.
Returns
Section titled “Returns”Promise<T>
The produced value, or the journaled value on a replay load.
Call Signature
Section titled “Call Signature”memoize<
T>(produce):T
Defined in: src/client/auth-client.ts:1160
Runs and journals a piece of your own async work so its result stays stable
across the 'redirect' flow.
In 'redirect' mode the page unloads on each step and signIn /
requestAttributes re-run on the return load, so a value you compute on the
first visit (from location, a fetch, crypto, …) would otherwise be
recomputed — and may differ — on the return. Wrap it in memoize: it runs
produce once on the first visit, journals the result, and replays that
result on the return load instead of re-running. Use it for a value the
post-flow code depends on, e.g. the URL to navigate to once sign-in
completes:
const next = await authClient.memoize( () => new URLSearchParams(location.search).get('next') ?? '/',);await authClient.signIn();location.assign(next); // the value captured before the redirectCall memoize in a stable order relative to signIn / requestAttributes
across loads (same order every load — branch only on values recovered from
earlier results), and keep the result JSON-serializable, since the journal
is JSON.
In 'window' mode there is no redirect, so this simply runs produce and
returns its result without persisting anything.
Mirrors the producer’s shape: a synchronous produce returns its value
directly, an asynchronous one returns a promise. Awaiting the result is
always safe (await on a non-promise is a no-op); the synchronous form lets
a value be memoized where an await is not possible, such as in a
constructor.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”produce
Section titled “produce”() => T
Produces the value to journal on the first load.
Returns
Section titled “Returns”T
The produced value, or the journaled value on a replay load.
requestAttributes()
Section titled “requestAttributes()”requestAttributes(
params):Promise<SignedAttributes>
Defined in: src/client/auth-client.ts:1071
Requests signed identity attributes from the identity provider.
The nonce is a callback that produces the 32-byte nonce (typically
fetched from the RP canister), returning a promise resolving to it. It is a
callback rather than a value so the redirect flow can journal the nonce and
reuse the exact same bytes when the flow replays on the return load,
instead of fetching a fresh single-use nonce that the signer never signed
against.
In ‘window’ mode the callback lets the identity provider window open while the nonce is still resolving, avoiding a perceived delay before the user sees the prompt; auto-close of the signer transport channel is temporarily disabled while awaiting so the window cannot be closed out from under the pending flow.
Parameters
Section titled “Parameters”params
Section titled “params”Request parameters.
string[]
Attribute keys to request (e.g. ['email', 'name']).
() => Promise<Uint8Array<ArrayBufferLike>>
Produces the 32-byte nonce issued by the RP canister, as a promise resolving to it.
Returns
Section titled “Returns”Promise<SignedAttributes>
Signed attribute data and signature.
Throws
Section titled “Throws”When the identity provider returns an error or an invalid response.
signIn()
Section titled “signIn()”signIn(
options?):Promise<Identity>
Defined in: src/client/auth-client.ts:802
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”Promise<Identity>
signOut()
Section titled “signOut()”signOut(
options?):Promise<void>
Defined in: src/client/auth-client.ts:1174
Clears the stored session and resets the client to an anonymous state.
Parameters
Section titled “Parameters”options?
Section titled “options?”Sign-out options.
returnTo?
Section titled “returnTo?”string
URL to navigate to after sign-out.
Returns
Section titled “Returns”Promise<void>
subscribe()
Section titled “subscribe()”subscribe(
listener): () =>void
Defined in: src/client/auth-client.ts:658
Watches who is signed in here, and returns a function that stops watching.
getStatus() and the predicates beside it are snapshots, so an application
rendering on them needs to be told when to read again. The record changes
for reasons that are nothing to do with this client — another tab signing
out, a sibling subdomain publishing a sign-in, a peer client on this page
re-issuing silently — and this is how those arrive.
Fired once the record is readable, so a listener asking who is signed in
sees what it was told about. It says that something changed and not what: a
listener reads the answer it wants, which for most is getStatus().
What it does not cover is the identity being replaced under an application that holds one — an app delegation rotating is deliberately invisible, and nothing about who is signed in has changed when it does.
Parameters
Section titled “Parameters”listener
Section titled “listener”() => void
Called after the record changes.
Returns
Section titled “Returns”A function that unregisters it.
() => void