Instance Properties

Instance properties configure the runtime behavior of this microservice per tenant instance. Schemas are defined in the instance_attributes MongoDB collection (instanceId: "-1" = platform-wide defaults). Managed via Webbox migrations only — never modified directly via API.
Source: webbox/v1.0.1/ migration files + src/domain/validator/userExtensions.ts InstanceProperties interface.

# Key Type Default Description
1 auth STRING "default" Login strategy for the instance. default — credential-based; facebook — Facebook OAuth; google — Google OAuth
2 searchEnabled BOOLEAN false true — indexes users in Typesense for full-text search; false — no search indexing, MongoDB lookup only
3 minUsernameLength STRING "3" Minimum chars required for a valid username; enforced at registration and profile update
4 list OBJECT {} Controls wish-list / save-for-later behavior; empty {} disables list features
5 pluginConfig OBJECT {} Plugin configuration (IAM connectors, SSO, validators, notification mappings). See pluginConfig.
6 idpConfig OBJECT {} External IdP settings for federated login; empty {} disables IdP-based authentication
7 allowedIdentities ARRAY ["email","phone","username"] Identity types accepted for registration; requests using unlisted types are rejected
8 allowedUpdates ARRAY ["email","phone","username"] Identity fields users can modify post-registration; unlisted fields are read-only
9 defaultGroupName STRING "" IAM group automatically assigned on user creation; empty "" skips group assignment
10 isUserMergeEnabled BOOLEAN true true — guest session merges into registered account on login; false — guest and registered sessions remain separate
11 enableBlacklistValidation BOOLEAN false true — rejects user creation if identity matches the GLOBAL blacklist; false — global blacklist not enforced
12 enableInstanceBlacklistValidation BOOLEAN false true — rejects user creation if identity matches the instance-scoped blacklist; false — instance blacklist not enforced
13 maxUsernameLength STRING "255" Maximum chars allowed for a username; enforced at registration and profile update
14 excludedProviderList ARRAY [] OAuth providers blocked from login; takes precedence over allowedProviderList; empty [] blocks none
15 allowedProviderList ARRAY [] Explicit whitelist of OAuth providers for login; empty [] allows all configured providers
16 userAddressLimit NUMBER 10 Max shipping/billing addresses a user can store; address creation fails once limit is reached
17 defaultLocale STRING "en" Locale applied to messages and content when no user preference is set (e.g., en_US, fr_FR)
18 guestUserExpiryInMins NUMBER 1440 Minutes before a guest user record expires and is purged; default 1440 = 24 hours
19 guestUserPrivilege STRING "guest" Privilege level assigned to unauthenticated/guest users; determines their accessible operations
20 storeId STRING "" Legacy store identifier retained for backward compatibility; empty "" if not in use
21 paymentAppId STRING "" App ID used to scope payment tokens to this instance; empty "" disables payment-app association
22 providerConfig OBJECT {} Per-provider payment gateway settings (keys, endpoints); empty {} uses platform defaults
23 allowedCardBrands ARRAY [] Card brands accepted for payment (e.g., visa, mastercard); empty [] allows all brands
24 allowedPaymentTypes ARRAY [] Payment method types accepted (e.g., card, wallet); empty [] allows all types
25 maxPaymentMethods NUMBER 10 Max payment methods a user can save; addition fails once limit is reached
26 siteUrl STRING — Public URL of the tenant storefront; used in email links and OAuth redirects
27 identifierType STRING — Primary identity field used for login and lookup; one of email, phone, or username
28 emailConfirmationRequired BOOLEAN false true — account access blocked until email is verified; false — account active immediately after self-registration
29 userActivationMethod STRING — LINK — sends a clickable email URL to activate account; OTP — sends a one-time code
30 otpMaxResendLimit NUMBER — Times a user can request a new OTP before the session is locked
31 otpMaxFailLimit NUMBER — Failed OTP entries allowed before the verification session is invalidated
32 userLimit NUMBER — Hard cap on total registered users for the instance; user creation fails when reached
33 passwordMinLength NUMBER — Minimum chars required for a valid password; enforced at registration and password change
34 passwordMaxLength NUMBER — Maximum chars allowed for a password; enforced at registration and password change
35 emailVerificationTokenTtlHours NUMBER 24 Hours before an email verification link expires and must be re-requested
36 activationTokenTtlHours NUMBER 48 Hours before an invite/activation link expires and must be re-sent

pluginConfig SSO Sub-Keys

Sub-key Description
pluginConfig.cognito.enabled true — activates AWS Cognito Hosted UI for authentication; false — Cognito login disabled
pluginConfig.cognito.userPoolId Cognito User Pool ID
pluginConfig.cognito.clientId Cognito App Client ID
pluginConfig.cognito.clientSecret Cognito App Client Secret
pluginConfig.cognito.region AWS region where the Cognito User Pool is hosted (e.g., us-east-1)
pluginConfig.cognito.domain Cognito Hosted UI domain
pluginConfig.cognito.redirectUri URI registered in Cognito that receives the authorization code after login
pluginConfig.oidc.enabled true — activates OIDC/OAuth2 login flow; false — OIDC provider disabled
pluginConfig.oidc.issuer OIDC issuer URL
pluginConfig.oidc.clientId OIDC client ID
pluginConfig.oidc.clientSecret OIDC client secret
pluginConfig.oidc.redirectUri OIDC callback URL
pluginConfig.oidc.authorizationEndpoint Authorization endpoint
pluginConfig.oidc.tokenEndpoint Token endpoint
pluginConfig.oidc.userInfoEndpoint UserInfo endpoint
pluginConfig.oidc.jwksUri JWKS URI for token validation
pluginConfig.saml.enabled true — activates SAML 2.0 SSO login; false — SAML provider disabled
pluginConfig.saml.entryPoint IdP URL the SP redirects to for SAML authentication initiation
pluginConfig.saml.issuer SP entity ID
pluginConfig.saml.cert IdP certificate (PEM)
pluginConfig.saml.callbackUrl SP ACS (callback) URL
pluginConfig.saml.signatureAlgorithm Signature algorithm (e.g., sha256)
pluginConfig.tokenExpirationHours SSO JWT token expiry (default: 24 hours)
pluginConfig.lifecycle.preHandlers Plugin hooks executed before user lifecycle events (create, update, delete)
pluginConfig.lifecycle.postHandlers Plugin hooks executed after user lifecycle events (create, update, delete)

Revision History
2026-08-04 | JP – Created the page and added the content.