Getting started

Meridian starts your integration in Sandbox. You will receive a Sandbox API Key, Sandbox Secret, and Program ID to build and test against the Meridian Accounts API.

​

Before you integrate

You need these Sandbox credentials from Meridian:

• API Key
• Secret
• Program ID

Use the Program ID when authenticating with the API.

​

Integration path

​

How Meridian identifies your customers

Your system keeps its own customer record. In Meridian, each of your customers maps to a single Meridian user. You supply externalId as your unique identifier for that customer. Use externalId whenever you need to refer to that customer from your system. Meridian returns userId as the Meridian identifier for that same user. You should store Meridian userId in your system after you first receive it. A Meridian user can belong to one or more programs. programId identifies the program context used when authenticating with the API and when Meridian sends webhook metadata.

​

Choose your integration and authentication model first

Before you implement token creation, decide:

• whether your Meridian Accounts integration is SINGLE_USER or MULTI_USER
• whether you are making a given request with partner HMAC authentication or a Meridian JWT bearer token

These decisions affect whether X-Meridian-User-Id is required, how your backend mints tokens, and which authentication headers later requests should send. Review these guides before building the auth flow:

• Choose your integration model
• Authentication overview
• Server-to-server authentication with HMAC
• Client-server authentication with JWT

​

Where you first see this

For a first-time MULTI_USER customer flow, create the Meridian user first with POST /v1/auth/users, then mint a token with POST /v1/auth/token. The create-user response is typically the first place you will see Meridian userId for that customer. Store that userId in your system so you can track the Meridian user alongside your own customer record and reuse it on later token requests.

​

Handling duplicate users

Meridian enforces uniqueness for externalId at the Meridian-user level. If you send POST /v1/auth/users with an externalId that has already been used, the request fails instead of creating another Meridian user for that customer. Before creating a user, determine whether the customer already has a Meridian userId in your system. If they do, use that userId to create the token, even if the customer still needs enrollment in the selected program. Store the returned userId when you first create the Meridian user, and rely on your own customer-to-user mapping on later token requests. This matters because Meridian users can belong to more than one program. A customer may already have a Meridian user record but still need enrollment in the program you selected for the current flow.

​

Next steps

After you receive your Sandbox credentials, review:

• Choose your integration model
• Authentication overview
• API reference overview
• Webhooks overview