Skip to content

AuthClient

Defined in: src/client/auth-client.ts:388

new AuthClient(options?): AuthClient

Defined in: src/client/auth-client.ts:427

AuthClientCreateOptions = {}

AuthClient

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.

void


getIdentity(): Promise<Identity>

Defined in: src/client/auth-client.ts:617

Returns the current identity, restoring a previous session if available.

Promise<Identity>


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.

Promise<NotificationConsentStatus>

Whether this application may notify the user.

Where this origin holds no live session.

const { granted } = await authClient.getNotificationConsentStatus();

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.

Principal | undefined


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.

SsoStatus | undefined

const client = new AuthClient({ ssoDomain: input.value });
client.subscribe(() => render(client.getSsoStatus()));
render(client.getSsoStatus());

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.

SessionStatus


isAuthenticated(): boolean

Defined in: src/client/auth-client.ts:653

Checks whether the user has an active, non-expired session.

boolean


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 redirect

Call 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.

T

() => Promise<T>

Produces the value to journal on the first load.

Promise<T>

The produced value, or the journaled value on a replay load.

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 redirect

Call 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.

T

() => T

Produces the value to journal on the first load.

T

The produced value, or the journaled value on a replay load.


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.

Promise<void>


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.

void


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.

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.

Promise<SignedAttributes>

Signed attribute data and signature.

When the identity provider returns an error or an invalid response.


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.

Promise<NotificationConsentStatus>

Whether this application may notify the user.

Where the client was built with prompt: 'none', which no consent ceremony can be run under.

Where this identity provider does not send notifications at all.

const { granted } = await authClient.requestNotificationConsent();

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.

Promise<void>

Where this origin holds no live session.


signIn(options?): Promise<Identity>

Defined in: src/client/auth-client.ts:923

AuthClientSignInOptions

Promise<Identity>


signOut(options?): Promise<void>

Defined in: src/client/auth-client.ts:1389

Clears the stored session and resets the client to an anonymous state.

Sign-out options.

string

URL to navigate to after sign-out.

Promise<void>


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.

() => void

Called after the record or the SSO status changes.

A function that unregisters it.

() => void