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

# Authentication

> How to authenticate with the MerchantSpring Public API using your API key.

The MerchantSpring Public API uses **API keys** for authentication. Every request must include your key in the `x-api-key` request header.

## Getting your API key

API keys are **provisioned automatically by MerchantSpring** — they are not generated from this documentation site.

To access your key, you must be an **Owner** or **Administrator** of an organisation that has API access enabled.

1. Sign in to [MerchantSpring](https://mm.merchantspring.io).
2. Go to **Settings → API**.
3. Click the reveal (eye) icon, then copy your key and store it securely — treat it like a password.

Each Owner and Administrator has their own individual key. The same page also shows your current plan and API usage.

<Note>
  Don't see the **API** tab? It's only visible to Owners and Administrators in organisations with API access enabled. If you are an Owner/Administrator and do not have access, contact MerchantSpring.
</Note>

<Warning>
  Keep your API key secret. Never embed it in client-side code, mobile apps, or public repositories. There is no self-service rotation — if a key is exposed, contact MerchantSpring to have it rotated.
</Warning>

## Making authenticated requests

Pass your key in the `x-api-key` header on every request:

```bash theme={null}
curl -X POST "https://mm-api.merchantspring.io/channels" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

<Note>
  You can also try any endpoint directly from the browser using the **playground** on each API Reference page — paste your key into the `x-api-key` field and press **Send**.
</Note>

## What your key determines

Your key is associated with:

* **Your user** — requests return data only for the channels your user can access.
* **Endpoint access** — some endpoints require additional access enabled on your key and is available on request — contact MerchantSpring to enable them.

## Error responses

| Status | Meaning                                                           |
| ------ | ----------------------------------------------------------------- |
| `400`  | Bad request — missing or invalid parameters in the body or query. |
| `401`  | Valid API key, but it doesn't have access to this endpoint.       |
| `403`  | Missing or invalid API key.                                       |
| `404`  | The requested resource (e.g. a `reportId`) was not found.         |

<Info>
  Usage limits (request rate and volume) are governed by the limits attached to your API key. If you need higher limits, talk to your MerchantSpring representative.
</Info>