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

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

## Your API key

Your API key is issued by Melio when your partner account is provisioned. It is a long, randomly generated string that 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.
* Rotate it 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 calls the health endpoint to confirm the key works:

```bash theme={null}
curl https://api.melio.com/v2/entites \
  -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."
  }
}
```