> ## 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.

# Getting started

> Set up your Meridian Accounts Sandbox credentials, understand how Meridian identifies your customers, and prepare for production access.

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

<Steps>
  <Step title="Receive Sandbox credentials">
    Meridian provides your Sandbox API Key, Sandbox Secret, and Program ID.
  </Step>

  <Step title="Build in Sandbox">
    Use those credentials to integrate your application with the Meridian
    Accounts API and webhooks in the Sandbox environment.
  </Step>

  <Step title="Complete certification">
    Meridian reviews and certifies your integration before enabling production
    access.
  </Step>

  <Step title="Move to production">
    After certification, Meridian provides your production API Key and Secret.
  </Step>
</Steps>

## 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.

| Identifier   | Issued by  | Purpose                                                                |
| :----------- | :--------- | :--------------------------------------------------------------------- |
| `externalId` | Integrator | Identifies your customer and enforces uniqueness in your system        |
| `userId`     | Meridian   | Identifies the Meridian user that represents that customer             |
| `programId`  | Meridian   | Identifies the program context for authentication and 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](/products/meridian-accounts/guides/choose-your-integration-model)
* [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)

## 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](/products/meridian-accounts/guides/choose-your-integration-model)
* [Authentication overview](/products/meridian-accounts/guides/authentication-overview)
* [API reference overview](/products/meridian-accounts/api-reference)
* [Webhooks overview](/products/meridian-accounts/webhooks)