Skip to content

Site Users ​

Visitor accounts: sign in, register, profile, saved cards and purchase history. Portal.siteUsers.create(moduleRef) returns a client for one Site Users module.

Quick start ​

ts
// Site Users is available as Portal.siteUsers

API reference ​

PortalSiteUsersSsoHandle ​

A single-sign-on flow (su.sso('google')).

complete() ​

On the return page: read code/state from the URL, POST the callback, establish the session.

ts
const siteUsersAuthResult = await siteUsersSsoHandle.complete();

Returns

Resolves with a PortalSiteUsersAuthResult: The answer to register(), login() and SSO completion.

start() ​

302 the browser to the provider consent screen (06).

ts
siteUsersSsoHandle.start();

su ​

A Site Users client for one module: account sign-in, profile, saved cards, purchases.

There is no loginFlow() / registerFlow() here; the mountable reference UI built on top of these calls is window.Portal.ui.siteUsers (PortalUiModuleAPI, in the separately-loaded UI bundle). A consumer building their own UI calls login() / register() directly instead.

addPaymentMethod() ​

Stores a card the provider SDK just tokenised (Stripe payment method id or Square source id).

ts
const directPaymentsSavedMethod = await su.addPaymentMethod(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.processor_reference_numstringYesThe processor's reference number.
payload.payment_method_idstringNo—
payload.source_idstringNoThe card token from the provider's own SDK.

Returns

Resolves with a PortalDirectPaymentsSavedMethod: A saved payment method (a vaulted card or wallet) of a payer.

cancelEmailChange() ​

Cancels the pending change.

ts
await su.cancelEmailChange();

Returns

Resolves when the call has completed.

changeEmail() ​

Nothing changes yet — a token is mailed to the NEW address, echoed back as pending so the caller can show "Confirm the link we sent to <pending>".

ts
const result = await su.changeEmail(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.emailstringYesAn e-mail address.
payload.current_passwordstringNo—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
pendingstringYesThe e-mail address the change is waiting to be confirmed to.

changePassword() ​

Changes the password (needs the current one).

ts
await su.changePassword(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.currentstringYes—
payload.nextstringYes—

Returns

Resolves when the call has completed.

config() ​

Reads the module's public settings.

ts
const siteUsersConfig = await su.config();

Returns

Resolves with a PortalSiteUsersConfig: The public settings of a Site Users module (su.config()), used to decide which sign-in options to draw.

confirmEmailChange() ​

Public, token-only — no session required to call this.

ts
const siteUserPublic = await su.confirmEmailChange(token);

Parameters

NameTypeRequiredDescription
tokenstringYesA token issued by the server (see the description above).

Returns

Resolves with a PortalSiteUserPublic: A signed-in site user, as safe to show in the browser.

confirmPayPalVault() ​

Second step of the PayPal vault flow, after the user approved at PayPal.

ts
const result = await su.confirmPayPalVault(processorRef, setupTokenId);

Parameters

NameTypeRequiredDescription
processorRefstringYesThe processor's reference.
setupTokenIdstringYesThe setup token from the PayPal approval step.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
successbooleanYesTrue when the call worked.
messagestringNoA message to show the visitor.

connections() ​

withBadges = false sends ?badges=0.

ts
const siteUserConnections = await su.connections(withBadges);

Parameters

NameTypeRequiredDescription
withBadgesbooleanNoInclude the count badges.

Returns

Resolves with an array of PortalSiteUserConnection.

init() ​

Loads the module's config and restores the session from storage. Call first.

ts
const siteUsersConfig = await su.init();

Returns

Resolves with a PortalSiteUsersConfig: The public settings of a Site Users module (su.config()), used to decide which sign-in options to draw.

isAuthenticated() ​

True when a session token is present (it may still have expired: me() is the real check).

ts
const ok = su.isAuthenticated();

Returns

Returns a boolean.

login() ​

Signs in with e-mail and password.

ts
const siteUsersAuthResult = await su.login(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.emailstringYesAn e-mail address.
payload.passwordstringYesThe password.

Returns

Resolves with a PortalSiteUsersAuthResult: The answer to register(), login() and SSO completion.

logout() ​

Signs out of this browser.

ts
await su.logout();

Returns

Resolves when the call has completed.

logoutAll() ​

Signs out of every device.

ts
await su.logoutAll();

Returns

Resolves when the call has completed.

me() ​

The signed-in user. Rejects when signed out.

ts
const siteUserPublic = await su.me();

Returns

Resolves with a PortalSiteUserPublic: A signed-in site user, as safe to show in the browser.

on() ​

Listens for sign-in, sign-out, registration and session expiry.

ts
su.on(event, handler);

Parameters

NameTypeRequiredDescription
eventstringYesThe event to listen for. One of login, logout, register, session:expired.
handler(payload?: unknown) => voidYesFunction called when it happens.

paymentMethods() ​

The user's saved cards, optionally of one processor.

ts
const directPaymentsSavedMethods = await su.paymentMethods(processorRef);

Parameters

NameTypeRequiredDescription
processorRefstringNoThe processor's reference.

Returns

Resolves with an array of PortalDirectPaymentsSavedMethod.

paymentMethodsFull() ​

paymentMethods()'s raw response, plus available_processors (which processor a first card could be vaulted against, when the merged list is empty).

ts
const result = await su.paymentMethodsFull(processorRef);

Parameters

NameTypeRequiredDescription
processorRefstringNoThe processor's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
payment_methodsPortalDirectPaymentsSavedMethod[]Yes—
available_processorsobject[]Yes—
available_processors[].processor_reference_numstringYesThe processor's reference number.
available_processors[].providerstringYesThe provider's name.

paymentsResolver() ​

Hand the result to Portal.directPayments.create(dpRef).useCustomerResolver(...).

ts
const directPaymentsPayerResolver = su.paymentsResolver();

Returns

Returns a PortalDirectPaymentsPayerResolver: The Direct Payments SDK remains a standalone product that does not import Site Users — it accepts this small interface, and Portal.siteUsers.create(module).paymentsResolver() is simply the one implementation that ships in this estate.

purchases() ​

The user's purchase history, cursor-paged.

ts
const result = await su.purchases(opts);

Parameters

NameTypeRequiredDescription
optsobjectNoOptional settings.
opts.scopestringNoWhich records to include.
opts.limitnumberNoThe most items to return.
opts.cursorstringNoThe cursor returned by the previous call, to get the next page.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
purchasesPortalPurchase[]Yes—
next_cursorstring | nullYes—
has_morebooleanYes—

register() ​

Creates an account (and signs in, unless e-mail verification is required).

ts
const siteUsersAuthResult = await su.register(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.emailstringNoAn e-mail address.
payload.usernamestringNoThe username.
payload.passwordstringNoThe password.
payload.display_namestringNoThe name shown to others.

Returns

Resolves with a PortalSiteUsersAuthResult: The answer to register(), login() and SSO completion.

removePaymentMethod() ​

Deletes a saved card.

ts
await su.removePaymentMethod(methodId, processorRef);

Parameters

NameTypeRequiredDescription
methodIdstringYesThe saved payment method's id.
processorRefstringYesThe processor's reference.

Returns

Resolves when the call has completed.

requestPasswordReset() ​

Mails a password-reset link. Always resolves, so it never reveals whether the address has an account.

ts
await su.requestPasswordReset(email);

Parameters

NameTypeRequiredDescription
emailstringYesAn e-mail address.

Returns

Resolves when the call has completed.

resendEmailChange() ​

Re-mails the same pending address.

ts
const result = await su.resendEmailChange();

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
pendingstringYesThe e-mail address the change is waiting to be confirmed to.

resendVerification() ​

Mails a new verification link to the signed-in user.

ts
await su.resendVerification();

Returns

Resolves when the call has completed.

resetPassword() ​

Sets a new password using the token from the reset e-mail.

ts
await su.resetPassword(token, password, password_confirmation);

Parameters

NameTypeRequiredDescription
tokenstringYesA token issued by the server (see the description above).
passwordstringYesThe password.
password_confirmationstringYes—

Returns

Resolves when the call has completed.

revokeSession() ​

Ends one session.

ts
await su.revokeSession(id);

Parameters

NameTypeRequiredDescription
idstring | numberYesThe record's id.

Returns

Resolves when the call has completed.

sessions() ​

The user's active sessions (devices).

ts
const result = await su.sessions();

Returns

Resolves with Array<Record<string, unknown>>.

setDefaultPaymentMethod() ​

Makes a saved card the default.

ts
await su.setDefaultPaymentMethod(methodId, processorRef);

Parameters

NameTypeRequiredDescription
methodIdstringYesThe saved payment method's id.
processorRefstringYesThe processor's reference.

Returns

Resolves when the call has completed.

setupPaymentMethod() ​

Starts adding a card: resolves with what the provider's SDK needs (for example a client secret).

ts
const result = await su.setupPaymentMethod(processorRef);

Parameters

NameTypeRequiredDescription
processorRefstringYesThe processor's reference.

Returns

Resolves with the server's record as a plain object.

setupPayPalVault() ​

PayPal's own two-step Vault flow.

ts
const result = await su.setupPayPalVault(processorRef);

Parameters

NameTypeRequiredDescription
processorRefstringYesThe processor's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
successbooleanYesTrue when the call worked.
messagestringNoA message to show the visitor.
setup_token_idstringNo—
client_idstringNo—

sso() ​

Prepares a single-sign-on flow with a provider from config().sso_providers. Call .start() on the login page, .complete() on the return page.

ts
const siteUsersSsoHandle = su.sso(provider);

Parameters

NameTypeRequiredDescription
providerstringYesThe provider's name.

Returns

Returns a PortalSiteUsersSsoHandle: A single-sign-on flow (su.sso('google')).

updateProfile() ​

Changes the display name or username.

ts
const siteUserPublic = await su.updateProfile(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.display_namestringNoThe name shown to others.
payload.usernamestringNoThe username.

Returns

Resolves with a PortalSiteUserPublic: A signed-in site user, as safe to show in the browser.

verifyEmail() ​

Confirms an e-mail address using the token from the verification e-mail.

ts
const siteUserPublic = await su.verifyEmail(token);

Parameters

NameTypeRequiredDescription
tokenstringYesA token issued by the server (see the description above).

Returns

Resolves with a PortalSiteUserPublic: A signed-in site user, as safe to show in the browser.

window.Portal.siteUsers ​

Portal.siteUsers — create a Site Users client.

Client ​

Constructs a client from a full options object.

Type: new (opts: PortalSiteUsersClientOptions) => PortalSiteUsersInstance

ts
const Client = window.Portal.siteUsers.Client;

create() ​

Creates a client for a module (the usual entry point).

ts
const siteUsersInstance = window.Portal.siteUsers.create(moduleId, opts);

Parameters

NameTypeRequiredDescription
moduleIdstringYes—
optsOmit<PortalSiteUsersClientOptions, 'module'>NoOptions of new Portal.siteUsers.Client() / create().

Returns

Returns a PortalSiteUsersInstance: A Site Users client for one module: account sign-in, profile, saved cards, purchases.

Types ​

PortalPurchase ​

One row of the user's purchase history, across every module.

NameTypeRequiredDescription
kindstringYesWhat was bought. One of order, event, appointment, subscription, invoice.
reference_numstringYesThe record's reference.
labelstringYesDisplay label.
module_keystring | nullYesThe module it came from.
instance_reference_numstring | nullYesThe module instance it came from.
invoice_refstring | nullYesThe Direct Payments invoice that paid for it.
processor_reference_numstring | nullYesThe processor that took the payment.
amount_centsnumberYesAmount in cents.
currencystringYesISO currency code.
statusstringYesPayment / order status.
refunded_centsnumberYesCents refunded.
paid_atstring | nullYesISO time paid.
placed_atstring | nullYesISO time placed.
manageobjectYesWhere the dashboard lets the user manage it (a view to open), or null.
manage.sectionstringYes—
manage.viewstringYesThe view key.
manage.refstringYesA reference.

PortalSiteUserConnection ​

A "connection" links a site user's account to one module instance (a store, an event...), so the account dashboard can show that module's data.

NameTypeRequiredDescription
module_keystringYesThe module, for example 'ecommerce'.
instance_reference_numstring | nullYesNull for a module-wide connection.
labelstringYesDisplay label.
capabilitiesstring[]YesAlready filtered for read-only (13) — never assume a capability the connection doesn't list.
settingsRecord<string, unknown>YesThe module's settings for the dashboard.
badgesRecord<string, number>YesView key → count, computed server-side. Empty when read-only.
status'active' | 'disconnected'Yesdisconnected connections stay readable but are read-only.
read_onlybooleanYesTrue when nothing may be changed.
read_only_noticestring | nullNoServer-supplied copy naming the instance — render verbatim at the top of the pane.

PortalSiteUserPublic ​

A signed-in site user, as safe to show in the browser.

NameTypeRequiredDescription
reference_numstringYesThe user's reference.
usernamestring | nullNoThe username, when the module uses them.
emailstring | nullNoThe user's e-mail.
display_namestring | nullNoThe name shown to others.
email_verified_atstring | nullNoISO time the e-mail was confirmed, or null.
is_activebooleanYesFalse for a blocked account.
created_atstringNoISO creation time.
pending_emailstring | nullNoThe address a live email-change token is pending confirmation to, or null/absent.

PortalSiteUsersAuthResult ​

The answer to register(), login() and SSO completion.

NameTypeRequiredDescription
successbooleanYesTrue when authentication worked.
tokenstringNoThe session token (when token storage is not cookie-based).
expires_atstringNoISO time the session expires.
userPortalSiteUserPublicNoThe signed-in user.

PortalSiteUsersClientOptions ​

Options of new Portal.siteUsers.Client() / create().

NameTypeRequiredDescription
modulestringNoThe Site Users module's reference.
baseUrlstringNoOverride the API base URL (pages on another origin).
tokenStorage'cookie' | 'memory' | 'localStorage'NoWhere the session token is kept: the su_session cookie (default), memory only, or localStorage.

PortalSiteUsersConfig ​

The public settings of a Site Users module (su.config()), used to decide which sign-in options to draw.

NameTypeRequiredDescription
modulestringYesThe module's reference.
allow_password_authbooleanYesWhether e-mail + password sign-in is allowed.
allow_registrationbooleanYesWhether visitors may create accounts themselves.
require_email_verificationbooleanYesWhether new accounts must confirm their e-mail.
require_usernamebooleanYesWhether a username is required at sign-up.
password_min_lengthnumberYesShortest allowed password.
sso_providersstring[]YesThe single-sign-on providers on offer, for example ['google'].