AuthClient
Defined in: src/client/auth-client.ts:388
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AuthClient(
options?):AuthClient
Defined in: src/client/auth-client.ts:427
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:798
Releases what this client hooked: the browser listeners, the state subscription, the refresh the identity has scheduled, and an SSO domain check still in progress. 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:617
Returns the current identity, restoring a previous session if available.
Returns
Section titled “Returns”Promise<Identity>
getNotificationConsentStatus()
Section titled “getNotificationConsentStatus()”getNotificationConsentStatus():
Promise<NotificationConsentStatus>
Defined in: src/client/auth-client.ts:1305
Whether this application may notify the signed-in user.
What a notifications control is painted from. A query, so the answer is uncertified, and it reports the consent alone: whether a notification would reach the user also depends on the device they hold, which this does not speak for.
Returns
Section titled “Returns”Promise<NotificationConsentStatus>
Whether this application may notify the user.
Throws
Section titled “Throws”Where this origin holds no live session.
Example
Section titled “Example”const { granted } = await authClient.getNotificationConsentStatus();getPrincipal()
Section titled “getPrincipal()”getPrincipal():
Principal|undefined
Defined in: src/client/auth-client.ts:678
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
getSsoStatus()
Section titled “getSsoStatus()”getSsoStatus():
SsoStatus|undefined
Defined in: src/client/auth-client.ts:728
Whether the organization domain this client was built with can be signed
in with, or undefined for a client built without ssoDomain.
Synchronous, and the same object until the answer changes, like
getStatus; subscribe says when to read it again. A client
built with ssoDomain starts checking as soon as it is built: it asks
Internet Identity to resolve the domain, then reads the result
until it is final, so checking lasts until Internet Identity answers.
Building the client also warms Internet Identity’s cache for the domain, so
a sign-in that follows starts without waiting on the fetch.
signIn proceeds in every state: Internet Identity resolves the domain itself during the sign-in, and explains a failure, a value that is not a domain included, on its own screen.
Returns
Section titled “Returns”SsoStatus | undefined
Example
Section titled “Example”const client = new AuthClient({ ssoDomain: input.value });client.subscribe(() => render(client.getSsoStatus()));render(client.getSsoStatus());getStatus()
Section titled “getStatus()”getStatus():
SessionStatus
Defined in: src/client/auth-client.ts:688
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:653
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:1374
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:1375
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.
ready()
Section titled “ready()”ready():
Promise<void>
Defined in: src/client/auth-client.ts:610
Resolves once this client has loaded the stored state and restored the session, so that isAuthenticated, getStatus and getPrincipal give the stored answer.
Only needed where there is no localStorage, which is a web worker or a
service worker. There the state is loaded from IndexedDB, and until then the
client reads as signed out:
const client = new AuthClient();await client.ready();client.isAuthenticated();In a browser tab, don’t wait for it. The status is correct from the moment the client is constructed, and waiting would hold up the page on IndexedDB and a session restore for nothing.
Rejects where restoring the session fails, as getIdentity does.
Returns
Section titled “Returns”Promise<void>
refreshSsoStatus()
Section titled “refreshSsoStatus()”refreshSsoStatus():
void
Defined in: src/client/auth-client.ts:742
Checks the organization domain again, for a “Try again” button.
The status goes back to checking and then to the new answer. Calling it
while an unavailable answer’s retryAfter is still in the future is
harmless: Internet Identity does not fetch again before then, so the answer
comes back the same at once. Nothing re-checks on its own once retryAfter
passes. Does nothing for an invalid domain, which no retry can fix, or for
a client built without ssoDomain.
Returns
Section titled “Returns”void
requestAttributes()
Section titled “requestAttributes()”requestAttributes(
params):Promise<SignedAttributes>
Defined in: src/client/auth-client.ts:1187
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; the signer keeps the channel open while the request waits for
its nonce. In both modes the request takes its place with the signer when
this method is called, so it can be issued alongside signIn in either
order.
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.
requestNotificationConsent()
Section titled “requestNotificationConsent()”requestNotificationConsent():
Promise<NotificationConsentStatus>
Defined in: src/client/auth-client.ts:1265
Asks the user whether this application may notify them.
Opens the identity provider the way a sign-in does, because consent is the user’s answer and nothing else can stand in for it. Where they agree, the browser they answered on is registered for delivery.
A refusal is an answer rather than a failure: it returns granted: false,
and an application renders that. Calling it again where consent is already
held returns what is recorded without asking a second time.
Returns
Section titled “Returns”Promise<NotificationConsentStatus>
Whether this application may notify the user.
Throws
Section titled “Throws”Where the client was built with
prompt: 'none', which no consent ceremony can be run under.
Throws
Section titled “Throws”Where this identity provider does not send notifications at all.
Example
Section titled “Example”const { granted } = await authClient.requestNotificationConsent();revokeNotificationConsent()
Section titled “revokeNotificationConsent()”revokeNotificationConsent():
Promise<void>
Defined in: src/client/auth-client.ts:1288
Withdraws this application’s consent to notify the user.
A canister call made as the session, so it needs no ceremony and opens nothing: the user already decided, and this records that they changed their mind. Idempotent — consent that is already withdrawn is not an error.
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”Where this origin holds no live session.
signIn()
Section titled “signIn()”signIn(
options?):Promise<Identity>
Defined in: src/client/auth-client.ts:923
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:1389
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:782
Watches who is signed in here, and the SSO status of a client built with
ssoDomain, and returns a function that stops watching.
getStatus(), getSsoStatus() and the predicates beside them 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. The SSO status changes when
Internet Identity answers. This is how both arrive.
Fired once the new answer is readable, so a listener sees what it was told
about. It says that something changed and not what: a listener reads the
answer it wants, getStatus() or getSsoStatus().
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 or the SSO status changes.
Returns
Section titled “Returns”A function that unregisters it.
() => void