Skip to main content
Before you implement authentication or onboarding, decide whether your Meridian Accounts integration is configured as SINGLE_USER or MULTI_USER. This is an integration configuration choice, not an authentication method. It determines how your partner credentials relate to Meridian users and whether X-Meridian-User-Id is required on partner-authenticated requests.

​
Integration types at a glance

Integration typeMeridian user representsX-Meridian-User-Id on partner-key callsPOST /v1/auth/usersCredential scope
SINGLE_USEROne fixed Meridian user configured for the partner integrationMust be omittedNot allowedOne partner credential set serves one fixed Meridian user
MULTI_USEROne Meridian user per customer or business you manageRequiredAllowedOne partner credential set can act on many Meridian users

​
Exact request rules

The Meridian Accounts API applies these rules to partner-key requests:
  • MULTI_USER: send X-Meridian-User-Id to identify which Meridian user the request targets
  • SINGLE_USER: omit X-Meridian-User-Id; Meridian uses the single configured user for that partner key
These rules apply when your backend is authenticating directly with Meridian by using partner credentials and HMAC.

​
How this affects token creation

When you call POST /v1/auth/token, the integration type changes how Meridian determines the user:
  • SINGLE_USER: Meridian derives the user from the partner key configuration, so X-Meridian-User-Id must not be sent
  • MULTI_USER: your request must identify the target user with X-Meridian-User-Id
If you are managing many customers, MULTI_USER also allows you to create or look up Meridian users and then mint access tokens for the correct user in the selected programId.

​
How this affects onboarding

SINGLE_USER and MULTI_USER do not change the program enrollment lifecycle, but they do change how you identify the user entering that lifecycle:
  • SINGLE_USER: onboarding operates on the one Meridian user already tied to the partner configuration
  • MULTI_USER: onboarding operates on the specific Meridian user identified by X-Meridian-User-Id
For MULTI_USER integrations, you should keep your own mapping between customer records, externalId, and Meridian userId. Persist the returned userId when the user is first created so later token requests can reuse that mapping. After choosing the integration model, continue with: