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

​
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: