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
// Site Users is available as Portal.siteUsersAPI 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.
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).
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).
const directPaymentsSavedMethod = await su.addPaymentMethod(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.processor_reference_num | string | Yes | The processor's reference number. |
payload.payment_method_id | string | No | — |
payload.source_id | string | No | The 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.
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>".
const result = await su.changeEmail(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.email | string | Yes | An e-mail address. |
payload.current_password | string | No | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
pending | string | Yes | The e-mail address the change is waiting to be confirmed to. |
changePassword()
Changes the password (needs the current one).
await su.changePassword(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.current | string | Yes | — |
payload.next | string | Yes | — |
Returns
Resolves when the call has completed.
config()
Reads the module's public settings.
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.
const siteUserPublic = await su.confirmEmailChange(token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | A 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.
const result = await su.confirmPayPalVault(processorRef, setupTokenId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
processorRef | string | Yes | The processor's reference. |
setupTokenId | string | Yes | The setup token from the PayPal approval step. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the call worked. |
message | string | No | A message to show the visitor. |
connections()
withBadges = false sends ?badges=0.
const siteUserConnections = await su.connections(withBadges);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
withBadges | boolean | No | Include the count badges. |
Returns
Resolves with an array of PortalSiteUserConnection.
init()
Loads the module's config and restores the session from storage. Call first.
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).
const ok = su.isAuthenticated();Returns
Returns a boolean.
login()
Signs in with e-mail and password.
const siteUsersAuthResult = await su.login(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.email | string | Yes | An e-mail address. |
payload.password | string | Yes | The password. |
Returns
Resolves with a PortalSiteUsersAuthResult: The answer to register(), login() and SSO completion.
logout()
Signs out of this browser.
await su.logout();Returns
Resolves when the call has completed.
logoutAll()
Signs out of every device.
await su.logoutAll();Returns
Resolves when the call has completed.
me()
The signed-in user. Rejects when signed out.
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.
su.on(event, handler);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | string | Yes | The event to listen for. One of login, logout, register, session:expired. |
handler | (payload?: unknown) => void | Yes | Function called when it happens. |
paymentMethods()
The user's saved cards, optionally of one processor.
const directPaymentsSavedMethods = await su.paymentMethods(processorRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
processorRef | string | No | The 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).
const result = await su.paymentMethodsFull(processorRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
processorRef | string | No | The processor's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
payment_methods | PortalDirectPaymentsSavedMethod[] | Yes | — |
available_processors | object[] | Yes | — |
available_processors[].processor_reference_num | string | Yes | The processor's reference number. |
available_processors[].provider | string | Yes | The provider's name. |
paymentsResolver()
Hand the result to Portal.directPayments.create(dpRef).useCustomerResolver(...).
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.
const result = await su.purchases(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | object | No | Optional settings. |
opts.scope | string | No | Which records to include. |
opts.limit | number | No | The most items to return. |
opts.cursor | string | No | The cursor returned by the previous call, to get the next page. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
purchases | PortalPurchase[] | Yes | — |
next_cursor | string | null | Yes | — |
has_more | boolean | Yes | — |
register()
Creates an account (and signs in, unless e-mail verification is required).
const siteUsersAuthResult = await su.register(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.email | string | No | An e-mail address. |
payload.username | string | No | The username. |
payload.password | string | No | The password. |
payload.display_name | string | No | The name shown to others. |
Returns
Resolves with a PortalSiteUsersAuthResult: The answer to register(), login() and SSO completion.
removePaymentMethod()
Deletes a saved card.
await su.removePaymentMethod(methodId, processorRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
methodId | string | Yes | The saved payment method's id. |
processorRef | string | Yes | The 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.
await su.requestPasswordReset(email);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
email | string | Yes | An e-mail address. |
Returns
Resolves when the call has completed.
resendEmailChange()
Re-mails the same pending address.
const result = await su.resendEmailChange();Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
pending | string | Yes | The e-mail address the change is waiting to be confirmed to. |
resendVerification()
Mails a new verification link to the signed-in user.
await su.resendVerification();Returns
Resolves when the call has completed.
resetPassword()
Sets a new password using the token from the reset e-mail.
await su.resetPassword(token, password, password_confirmation);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | A token issued by the server (see the description above). |
password | string | Yes | The password. |
password_confirmation | string | Yes | — |
Returns
Resolves when the call has completed.
revokeSession()
Ends one session.
await su.revokeSession(id);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | number | Yes | The record's id. |
Returns
Resolves when the call has completed.
sessions()
The user's active sessions (devices).
const result = await su.sessions();Returns
Resolves with Array<Record<string, unknown>>.
setDefaultPaymentMethod()
Makes a saved card the default.
await su.setDefaultPaymentMethod(methodId, processorRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
methodId | string | Yes | The saved payment method's id. |
processorRef | string | Yes | The 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).
const result = await su.setupPaymentMethod(processorRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
processorRef | string | Yes | The processor's reference. |
Returns
Resolves with the server's record as a plain object.
setupPayPalVault()
PayPal's own two-step Vault flow.
const result = await su.setupPayPalVault(processorRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
processorRef | string | Yes | The processor's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the call worked. |
message | string | No | A message to show the visitor. |
setup_token_id | string | No | — |
client_id | string | No | — |
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.
const siteUsersSsoHandle = su.sso(provider);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | The provider's name. |
Returns
Returns a PortalSiteUsersSsoHandle: A single-sign-on flow (su.sso('google')).
updateProfile()
Changes the display name or username.
const siteUserPublic = await su.updateProfile(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.display_name | string | No | The name shown to others. |
payload.username | string | No | The 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.
const siteUserPublic = await su.verifyEmail(token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | A 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
const Client = window.Portal.siteUsers.Client;create()
Creates a client for a module (the usual entry point).
const siteUsersInstance = window.Portal.siteUsers.create(moduleId, opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
moduleId | string | Yes | — |
opts | Omit<PortalSiteUsersClientOptions, 'module'> | No | Options 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.
| Name | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | What was bought. One of order, event, appointment, subscription, invoice. |
reference_num | string | Yes | The record's reference. |
label | string | Yes | Display label. |
module_key | string | null | Yes | The module it came from. |
instance_reference_num | string | null | Yes | The module instance it came from. |
invoice_ref | string | null | Yes | The Direct Payments invoice that paid for it. |
processor_reference_num | string | null | Yes | The processor that took the payment. |
amount_cents | number | Yes | Amount in cents. |
currency | string | Yes | ISO currency code. |
status | string | Yes | Payment / order status. |
refunded_cents | number | Yes | Cents refunded. |
paid_at | string | null | Yes | ISO time paid. |
placed_at | string | null | Yes | ISO time placed. |
manage | object | Yes | Where the dashboard lets the user manage it (a view to open), or null. |
manage.section | string | Yes | — |
manage.view | string | Yes | The view key. |
manage.ref | string | Yes | A 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.
| Name | Type | Required | Description |
|---|---|---|---|
module_key | string | Yes | The module, for example 'ecommerce'. |
instance_reference_num | string | null | Yes | Null for a module-wide connection. |
label | string | Yes | Display label. |
capabilities | string[] | Yes | Already filtered for read-only (13) — never assume a capability the connection doesn't list. |
settings | Record<string, unknown> | Yes | The module's settings for the dashboard. |
badges | Record<string, number> | Yes | View key → count, computed server-side. Empty when read-only. |
status | 'active' | 'disconnected' | Yes | disconnected connections stay readable but are read-only. |
read_only | boolean | Yes | True when nothing may be changed. |
read_only_notice | string | null | No | Server-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.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The user's reference. |
username | string | null | No | The username, when the module uses them. |
email | string | null | No | The user's e-mail. |
display_name | string | null | No | The name shown to others. |
email_verified_at | string | null | No | ISO time the e-mail was confirmed, or null. |
is_active | boolean | Yes | False for a blocked account. |
created_at | string | No | ISO creation time. |
pending_email | string | null | No | The address a live email-change token is pending confirmation to, or null/absent. |
PortalSiteUsersAuthResult
The answer to register(), login() and SSO completion.
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when authentication worked. |
token | string | No | The session token (when token storage is not cookie-based). |
expires_at | string | No | ISO time the session expires. |
user | PortalSiteUserPublic | No | The signed-in user. |
PortalSiteUsersClientOptions
Options of new Portal.siteUsers.Client() / create().
| Name | Type | Required | Description |
|---|---|---|---|
module | string | No | The Site Users module's reference. |
baseUrl | string | No | Override the API base URL (pages on another origin). |
tokenStorage | 'cookie' | 'memory' | 'localStorage' | No | Where 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.
| Name | Type | Required | Description |
|---|---|---|---|
module | string | Yes | The module's reference. |
allow_password_auth | boolean | Yes | Whether e-mail + password sign-in is allowed. |
allow_registration | boolean | Yes | Whether visitors may create accounts themselves. |
require_email_verification | boolean | Yes | Whether new accounts must confirm their e-mail. |
require_username | boolean | Yes | Whether a username is required at sign-up. |
password_min_length | number | Yes | Shortest allowed password. |
sso_providers | string[] | Yes | The single-sign-on providers on offer, for example ['google']. |