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

# Authentication

> Pass your API key in the api-key request header to authenticate every call to the Melio Payouts API. Learn how to handle auth errors.

The Melio B2B Payouts API authenticates every request using an API key that you pass in the `api-key` request header. There are no cookies and no OAuth flows - every call must include this header, and requests that omit it or supply an invalid key are rejected immediately.

<Note>
  The Melio-hosted account-link flow uses a short-lived, scoped session token (a bearer JWT minted by `POST /accounts/link` and embedded in the returned link's URL). It authenticates only the hosted page's own calls on the entity's behalf - your server-to-server requests always use the `api-key` header.
</Note>

## Your API key

Your API key is issued by Melio when your partner account is provisioned. The API key uniquely identifies your integration. Treat it like a password:

* Never commit it to source control.
* Never expose it in client-side code or browser requests.
* Generate a new API key immediately if you suspect it has been compromised.

## Sending the key

Pass your key in the `api-key` header on every request. The example below lists your entities to confirm the key works:

```bash theme={null}
curl https://api.melio.com/v2/entities \
  -H "api-key: YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with the key you received from Melio. Do not add a `Bearer` prefix — the header value is the raw key string.

## The Melio-Entity-Id header

Endpoints that operate on behalf of a specific business entity — including account, payment, and limitation endpoints — also require a `Melio-Entity-Id` header. Set this header to the `id` of the entity you created (e.g. `ent_a1b2c3d4-e5f6-7890-abcd-ef1234567890`). If you are a partner with only a single entity, you may use the sentinel value `me` instead of the full ID.

The following example creates a payment on behalf of a specific entity:

```bash theme={null}
curl -X POST https://api.melio.com/v2/payments \
  -H "api-key: YOUR_API_KEY" \
  -H "Melio-Entity-Id: ent_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Omitting `Melio-Entity-Id` on an endpoint that requires it returns a `400 Bad Request` error.

## Authentication errors

<Warning>
  Authentication failures return a `401 Unauthorized` HTTP status. They indicate a problem with your API key — not with the resource you are trying to access. Check that the key is correctly copied, has not been rotated, and is being passed in the `api-key` header (not `Authorization`).
</Warning>

| Code                | HTTP Status | Meaning                                                                                              |
| ------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`      | 401         | The `api-key` header is missing, malformed, or the key value is not recognized.                      |
| `NO_ACTIVE_API_KEY` | 401         | The key was valid at some point but no active API key exists for your account (e.g. it was revoked). |

All authentication errors follow this response shape:

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "UNAUTHORIZED",
    "message": "The provided API key is invalid or missing."
  }
}
```