Skip to main content
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.
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.

​
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:
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:
Omitting Melio-Entity-Id on an endpoint that requires it returns a 400 Bad Request error.

​
Authentication errors

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).
All authentication errors follow this response shape: