> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose your integration model

> Understand how SINGLE_USER and MULTI_USER integrations differ and how that choice affects authentication and onboarding.

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 type | Meridian user represents                                       | `X-Meridian-User-Id` on partner-key calls | `POST /v1/auth/users` | Credential scope                                          |
| :--------------- | :------------------------------------------------------------- | :---------------------------------------- | :-------------------- | :-------------------------------------------------------- |
| `SINGLE_USER`    | One fixed Meridian user configured for the partner integration | Must be omitted                           | Not allowed           | One partner credential set serves one fixed Meridian user |
| `MULTI_USER`     | One Meridian user per customer or business you manage          | Required                                  | Allowed               | One 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.

## Recommended reading order

After choosing the integration model, continue with:

* [Authentication overview](/products/meridian-accounts/guides/authentication-overview)
* [Server-to-server authentication with HMAC](/products/meridian-accounts/guides/server-to-server-authentication-with-hmac)
* [Client-server authentication with JWT](/products/meridian-accounts/guides/client-server-authentication-with-jwt)