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

# Authentication

> Authenticate with your API key, and understand the key and account states that can block access.

Every request to the Merchant API must include your secret key in the **`X-Api-Key`** header. There are no other auth schemes — no OAuth, no bearer tokens.

```bash theme={null}
curl https://api.manexx.com/api/v1/external/rates \
  -H "X-Api-Key: manexx_live_your_key_here"
```

## Getting your key

Your API key is issued per business from the dashboard. The same place also holds your **webhook secret**, which is separate and used only to verify webhook signatures — see [WebHooks](/webhooks#verifying-the-signature).

<Callout>
  The API key is a secret. Send it only from your server — never from a browser, mobile app, or committed code. If it leaks, revoke it in the dashboard; the old key stops working immediately.
</Callout>

## How requests are checked

Each request is validated in order:

<Steps>
  <Step title="Key present and known" title-type="p">
    A missing or unrecognized key is rejected with `401 API_KEY_INVALID`. An unknown key returns the same error as a missing one — we don't reveal whether a key exists.
  </Step>

  <Step title="Key active" title-type="p">
    A revoked key returns `403 API_KEY_REVOKED`.
  </Step>

  <Step title="Business active" title-type="p">
    If your business isn't in the `active` state, the request is rejected with `403 BUSINESS_NOT_ACTIVE`, and `details.status` carries the current state.
  </Step>

  <Step title="Account not blocked" title-type="p">
    If the account is blocked, the request is rejected with `403 MERCHANT_BLOCKED`.
  </Step>
</Steps>

## Errors

| Code                  | HTTP  | When                                      |
| --------------------- | ----- | ----------------------------------------- |
| `API_KEY_INVALID`     | `401` | `X-Api-Key` missing or not recognized     |
| `API_KEY_REVOKED`     | `403` | The key was revoked                       |
| `BUSINESS_NOT_ACTIVE` | `403` | Business is not active (`details.status`) |
| `MERCHANT_BLOCKED`    | `403` | The account is blocked                    |

## Account & key states

<ResponseField name="Key revoked">
  A key can be revoked from the dashboard, or automatically when a business is banned. All requests with it return `403 API_KEY_REVOKED`. Issue a new key to restore access.
</ResponseField>

<ResponseField name="Business not active">
  Only an `active` business can call the API. Other states — such as `pending_verification`, `ready_to_start`, `rejected`, or `banned` — return `403 BUSINESS_NOT_ACTIVE` with the exact state in `details.status`.
</ResponseField>

<ResponseField name="Account blocked">
  If the underlying account is blocked, every request returns `403 MERCHANT_BLOCKED` regardless of key or business state.
</ResponseField>

<Callout>
  A `403` here is about your account, not the specific request — retrying won't help until the key, business, or account state is resolved. Resolve it in the dashboard or with support.
</Callout>

## Rate limiting

Requests are rate limited per API key. Over the limit returns `429 RATE_LIMITED`; back off and retry. See [Errors](/errors#rate-limiting).