AuthClient

Manages authentication and identity for Internet Computer web apps.

Example

const authClient = new AuthClient();

const identity = authClient.isAuthenticated()
  ? await authClient.getIdentity()
  : await authClient.signIn();

Constructors

Constructor

new AuthClient(options?): AuthClient

Defined in: auth-client.ts:204

Parameters

options?

AuthClientCreateOptions = {}

Returns

AuthClient

Properties

idleManager

idleManager: IdleManager | undefined

Defined in: auth-client.ts:202

Methods

getIdentity()

getIdentity(): Promise<Identity>

Defined in: auth-client.ts:252

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

Returns

Promise<Identity>

isAuthenticated()

isAuthenticated(): boolean

Defined in: auth-client.ts:260

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

Returns

boolean

memoize()

Call Signature

memoize<T>(produce): Promise<T>

Defined in: auth-client.ts:514

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.

Type Parameters

T

T

Parameters

produce

() => Promise<T>

Produces the value to journal on the first load.

Returns

Promise<T>

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

Call Signature

memoize<T>(produce): T

Defined in: auth-client.ts:515

Runs and journals a piece of your own async work so its result stays stable across the 'redirect' flow.

const next = await authClient.memoize(
  () => new URLSearchParams(location.search).get('next') ?? '/',
);
await authClient.signIn();
location.assign(next); // the value captured before the redirect

In 'window' mode there is no redirect, so this simply runs produce and returns its result without persisting anything.

Type Parameters

T

T

Parameters

produce

() => T

Produces the value to journal on the first load.

Returns

T

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

requestAttributes()

requestAttributes(params): Promise<SignedAttributes>

Defined in: auth-client.ts:441

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

params

Request parameters.

keys

string[]

Attribute keys to request (e.g. ['email', 'name']).

nonce

() => Promise<Uint8Array<ArrayBufferLike>>

Produces the 32-byte nonce issued by the RP canister, as a promise resolving to it.

Returns

Promise<SignedAttributes>

Signed attribute data and signature.

Throws

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

signIn(options?): Promise<Identity>

Defined in: auth-client.ts:284

Opens the identity provider, requests a delegation, and returns the authenticated identity.

Parameters

options?

AuthClientSignInOptions

Sign-in options.

Returns

Promise<Identity>

The authenticated identity.

Throws

When authentication fails.

Example

try {
  const identity = await authClient.signIn();
} catch (error) {
  console.error('Sign-in failed:', error);
}

signOut()

signOut(options?): Promise<void>

Defined in: auth-client.ts:529

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

Parameters

options?

Sign-out options.

returnTo?

string

URL to navigate to after sign-out.

Returns

Promise<void>