Authentication

Melo uses the client credentials flow for machine-to-machine authentication. Credentials belong to one merchant and determine which warehouses and transfers are accessible.

Get your credentials

Developer credentials are issued from the Melo dashboard once your merchant account has a warehouse.

1. Open the dashboard. Go to dash.melo.delivery.
2. Register an account. Sign up and confirm your account.
3. Add a merchant. Create the merchant that will own your deliveries and balance.
4. Add a warehouse. Register at least one warehouse to use as a pickup point.
5. Copy your developer credentials. Once the merchant and warehouse exist, the dashboard issues a client_id and client_secret for that merchant.

Credentials are scoped to the merchant they were issued for, so they can only access that merchant's warehouses and transfers.

Test mode

You can hold two credential sets: a live pair and a test pair. Create, view, regenerate, and revoke each set independently from the dashboard. Each set has its own status.

• Test client_id values start with melo_test_. Live ones start with melo_.
• Authentication is the same for both: POST /auth/token with grant_type=client_credentials, then Authorization: Bearer YOUR_ACCESS_TOKEN.
• The mode is decided by which credential set minted the token. There is no header, query parameter, or separate base URL, so the same code works for both by swapping credentials.
• The client_secret is shown only when it is created or regenerated. Copy it then.

Use test credentials to build and verify your integration without affecting real deliveries or your balance, then switch to live credentials to go live. No other code changes are needed. See Test mode for how each endpoint behaves.

Keep credentials server-side

Your client_secret must remain confidential. Do not embed it in frontend JavaScript, mobile applications, public repositories, logs, or analytics events.

Exchange credentials

Send the credentials to POST /auth/token:

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

The API returns an access token with a lifetime of 3,600 seconds. Include it in protected requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Token lifecycle

• Cache the token in your server process or secure shared cache.
• Refresh it before the expires_in period ends.
• When a request returns ACCESS_TOKEN_EXPIRED, obtain a new token and retry once.
• Do not request a new token for every API call.
• Never log access tokens or authorization headers.

Authentication errors

See Errors for the standard error envelope and retry guidance.