AuthClientBaseOptions

All of them together, because they make one claim: the page being shown, the window regaining focus, a pointer or a key. A backgrounded tab has its timers throttled, so its delegation can lapse while nobody is looking and the first click after coming back waits for a mint; returning to the tab is early enough to hide that.

Nothing is hooked where there is no DOM, so a client outside a browser needs no option. Setting it makes requests the only thing that says this session is in use — including to the identity provider, which ends a session nothing has minted from for long enough. An application whose users read more than they click should leave it alone.

Default

false

hint?

optional hint?: Principal

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

The account to re-issue for, which is the principal the state names.

Sent as text in a hint query param on the authorize URL; Internet Identity uses it to pick which session a prompt 'none' request resolves to when the user has more than one for this app. Inspired by OpenID Connect’s login_hint.

identityProvider?

optional identityProvider?: object

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

Where the identity provider is, as two values rather than one.

A ceremony is rendered at a URL and delegations are minted by a canister, and they are not the same address: a custom domain can front the mainnet canister, and a local deployment changes both. Nothing is derived from the URL — the origin of one is not a promise about which canister answers there — so a deployment is named by both or by neither. Omit the option and both are mainnet’s.

authorizeUrl

authorizeUrl: string | URL

The authorize URL a ceremony is rendered at.

canisterId

canisterId: string | Principal

The canister that mints and revokes this application’s delegations.

namespace?

optional namespace?: string

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

Prefix for every slot this client writes under.

Slots are assigned in one place rather than defaulted by each store, and this moves all of them at once — so an application running two clients under one origin separates them with a single string and cannot rename some while missing others.

Leave it unset unless a second client shares this origin.

prompt?

optional prompt?: "none" | "login"

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

Whether Internet Identity may answer without user interaction.

'login' (the effect of omitting it): run a normal sign-in ceremony.
'none': Internet Identity answers from a session it already holds for this app and returns without rendering anything, or fails with an interaction_required error if it cannot. Pair with hint to name which account to re-issue for. Use it on a page load where the state names an account this origin has no credentials for — a sibling subdomain signed in — so this origin acquires its own without a ceremony.

Sent as a prompt query param on the authorize URL. An Internet Identity extension inspired by OpenID Connect’s prompt, and not part of any ICRC standard — which is why it travels on the URL rather than in the request.

resumable?

optional resumable?: boolean

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

Whether Internet Identity may keep this sign-in so that a later prompt 'none' request can be answered from it.

Defaults to what AuthClientCreateOptions.stateStorage says, which is true only for CookieStateStorage: an application declares this intent by choosing a store whose record reaches its siblings, and making it say so a second time would be noise. Set it here for a cross-origin arrangement that is not sibling subdomains, or to force it off for siblings that should each sign in properly.

Off means the provider keeps no session for this app on this device, so there is nothing for a silent request to find. It says nothing about how long a session lasts: AuthClientSignInOptions.maxTimeToIdle applies either way.

Sent as a resumable query param on the authorize URL, for the same reason prompt is: the URL is assembled once, here.

stateStorage?

optional stateStorage?: StateStorage

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

Where the state of the sign-in is kept: which account is signed in here, and until when. Defaults to localStorage.

transport?

optional transport?: "window" | "redirect"

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

How the client communicates with the identity provider.

'window' (default) — the identity provider opens in a separate browser tab or window (a popup when windowOpenerFeatures is set) and communicates over the ICRC-29 postMessage transport.
'redirect' — the current page navigates to the identity provider over the ICRC-167 URL transport, which returns to this same page. The callback URL is the current page’s URL (location.origin + location.pathname), so that page must be on an origin you control and declared in that origin’s /.well-known/ii-auth-callbacks allow-list. Use it for full-page sign-in that shouldn’t need a user gesture to open a window (e.g. redirecting on a restricted route), or native apps handing off via universal links.

With 'redirect' the page unloads on each step and the flow re-runs on the return load, so call signIn / requestAttributes directly on the page’s load (not deferred behind, say, a click handler): a fresh visit starts the flow and the identity provider’s return replays it to completion. Give each flow its own route so its persisted state stays isolated.

Default

'window'

See

https://github.com/dfinity/wg-identity-authentication/blob/main/topics/icrc_167_browser_url_transport.md

windowOpenerFeatures?

optional windowOpenerFeatures?: string

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

Window features string for the authentication popup.

Example

"toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100"