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

# Authentication

> The recommended authentication scheme for a partner-hosted Credit API, and the alternatives Meridian supports.

Because the bank partner hosts the Credit API, the bank owns the authentication scheme. Meridian is the calling client and adapts to what the bank provides.

## Recommended: OAuth 2.0 client credentials

Issue Meridian OAuth 2.0 client credentials and accept the resulting token as a bearer token on every request:

```http theme={null}
POST /credits/commit HTTP/1.1
Host: api.examplebank.com
Authorization: Bearer <access_token>
Content-Type: application/json
```

This is the reference default in the specification. It is well understood, requires no custom tooling on either side, and plugs into Meridian's integration layer with no bespoke work.

## Also supported

If OAuth 2.0 is not viable for your institution, Meridian supports these alternatives. The concrete scheme is agreed during onboarding.

| Scheme                              | Notes                                                                     |
| :---------------------------------- | :------------------------------------------------------------------------ |
| mTLS                                | Mutual TLS with certificates exchanged during onboarding                  |
| HMAC request signing                | Shared-secret signature over the canonical request                        |
| IP allowlisting                     | Meridian provides egress IP ranges; typically layered with another scheme |
| Asymmetric payload signatures (RSA) | Signed request payloads using an exchanged public key                     |

These can be combined. IP allowlisting in particular is usually applied alongside OAuth or mTLS rather than on its own.

## What live integrations tend to look like

The bearer token above is the cleanest starting point, but bank Credit APIs in production rarely stop there. When scoping your build, expect that one or more of the following may apply, and raise them with Meridian early because each one adds integration time:

| Pattern                   | What it means in practice                                                                                                                       |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| Request signing           | A signature over the canonical request body, typically RSA or HMAC SHA-256, sent alongside the payload rather than as an `Authorization` header |
| Field-level encryption    | Account numbers, account names, and other PII encrypted individually inside the JSON body, using a public key exchanged during onboarding       |
| Credentials in the body   | Partner codes, passwords, or client secrets carried inside the request payload instead of in headers                                            |
| Per-request token minting | A fresh token for every call, where the institution invalidates the previous one and caching is therefore not possible                          |
| Layered schemes           | Several of the above applied at once, for example a token plus a static API key header plus a request hash                                      |

None of these are problems, and Meridian implements them today for existing partners. They matter for planning. An integration using signing and field-level encryption takes meaningfully longer to certify than one using a bearer token alone, so decide early which of these your institution requires.

<Tip>
  If you are free to choose, OAuth 2.0 client credentials with a bearer token is the fastest path to production.
</Tip>

## Requirements regardless of scheme

<Warning>
  Credentials must be **environment-scoped**. Sandbox and production must use separate credentials, and a sandbox credential must never be accepted by production.
</Warning>

* All traffic is HTTPS with TLS 1.2 or higher.
* Authentication failures return `401` with an `ApiError` body. Do not return `200` with a failure status for an authentication problem. See [business failures vs transport failures](/products/bank-transfers/credit-api-example/index#business-failures-vs-transport-failures).
* Token or credential rotation should be possible without downtime. Tell Meridian your rotation cadence during onboarding.