User Auth initialization

The User Auth initializer configures authentication and authorization features including login, registration, password management, and session handling. Use initialization to customize authentication flows and user data models.

Version: 4.0.0

Configuration options

Parameter	Type	Req?	Description
langDefinitions	LangDefinitions	No	Overrides built-in text strings for localization or custom branding. Maps locale keys to replacement dictionary values.
models	Record<string, any>	No	Extends or replaces default data models. Provide custom fields and transformer functions to modify data returned from the backend.
authHeaderConfig	authHeaderConfig	No	Sets the HTTP header name and token prefix (for example, Bearer or Token) used in authentication requests.
customerPermissionRoles	boolean	No	When true, fetches customer B2B role permissions after sign-in and emits them via the auth/permissions event.
adobeCommerceOptimizer	boolean	No	When true, enables Adobe Commerce Optimizer support. Token validation also fetches customer.group.uid and emits it via the auth/group-uid event for price book resolution. Calls getAdobeCommerceOptimizerData after sign-in.

Default configuration

The initializer runs with these defaults when no configuration is provided:

scripts/initializers/user-auth.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-auth';

// All configuration options are optional
await initializers.mountImmediately(initialize, {
  langDefinitions: {}, // Uses built-in English strings
  models: {}, // Uses default data models
  // Drop-in-specific defaults:
  // authHeaderConfig: undefined // See configuration options below
  // customerPermissionRoles: undefined // See configuration options below
  // adobeCommerceOptimizer: undefined // See configuration options below
});

Language definitions

Override dictionary keys for localization or branding. The langDefinitions object maps locale keys to custom strings that override default text for the drop-in.

scripts/initializers/user-auth.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-auth';

const customStrings = {
  'AddToCart': 'Add to Bag',
  'Checkout': 'Complete Purchase',
  'Price': 'Cost',
};

const langDefinitions = {
  default: customStrings,
};

await initializers.mountImmediately(initialize, { langDefinitions });

Tip

For complete dictionary customization including all available keys and multi-language support, see the User Auth Dictionary page.

Customizing data models

Extend or transform data models by providing custom transformer functions. Use the models option to add custom fields or modify existing data structures returned from the backend.

Available models

Model	Description
CustomerModel	Transforms customer authentication data including profile information, addresses, and account settings. Use this to add custom fields or modify user data structures.

To customize CustomerModel, provide a transformer function that receives the raw GraphQL response and returns the shape your storefront needs:

scripts/initializers/user-auth.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-auth';

const models = {
  CustomerModel: {
    transformer: (data) => ({
      // Add custom fields from backend data
      customField: data?.custom_field,
      promotionBadge: data?.promotion?.label,
      // Transform existing fields
      displayPrice: data?.price?.value ? `${data.price.value}` : 'N/A',
    }),
  },
};

await initializers.mountImmediately(initialize, { models });

Drop-in configuration

The following example shows all drop-in-specific options enabled together. Use it as a starting point when you need B2B role permissions and Adobe Commerce Optimizer support in the same storefront.

scripts/initializers/user-auth.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-auth';

await initializers.mountImmediately(initialize, {
  langDefinitions: {},
  authHeaderConfig: {},
  customerPermissionRoles: true,
  adobeCommerceOptimizer: true,
  models: {},
});

Note

Refer to the Configuration options table for detailed descriptions of each option.

Configuration types

authHeaderConfig

Configures the authentication header format for API requests, including custom header names and token prefix format (for example, Bearer or Token).

authHeaderConfig?: {
    header: string;
    tokenPrefix: string;
  }

langDefinitions

Maps locale identifiers to dictionaries of key-value pairs. The default locale is used as the fallback when no specific locale matches. Each dictionary key corresponds to a text string used in the drop-in UI.

langDefinitions?: {
  [locale: string]: {
    [key: string]: string;
  };
};

models

Maps model names to transformer functions. Each transformer receives data from GraphQL and returns a modified or extended version. Use the Model<T> type from @dropins/tools to create type-safe transformers.

models?: {
  [modelName: string]: Model<any>;
};

Model definitions

CustomerModel

export interface CustomerModel {
  firstName: string;
  lastName: string;
  email: string;
  groupUid: string;
  customAttributes?: Record<string, string>[];
  errors?: { message: string }[];
}