> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/authentication.md).

# Authentication

How API calls are authenticated with the X-OrderEazi-Key header, which permissions a key can have, and what happens when a key is missing or isn't allowed.

Every call you make to the OrderEazi API carries an API key, so OrderEazi knows which system is calling and what it may see. The organisation creates each key in OrderEazi and gives it its own permissions.

### Before you start

Someone in the organisation with the **API Keys** permission, in the **Integrations** permission group, creates your key under **Integrations** > **API Keys** and shares it with you securely. See [API Keys](/central/order-management/integrations/api-keys.md).

### How to send your key

Put the key in the `X-OrderEazi-Key` header of every request:

```bash
curl https://yourcompany.ordereazi.com/api/client/list \
  -H "X-OrderEazi-Key: YOUR_API_KEY" \
  -H "x-api-version: 2.0"
```

Always call the API over HTTPS. Keep the key out of code that runs in a browser or a mobile app, where anyone can read it. Call the API from your server instead.

### What a key can do

Each key has **Read** and **Write** permissions for each area of data. An endpoint needs the permission for its area, and some need more than one. The [API reference](/central/developers/finding-your-api-reference.md) shows what each endpoint needs.

| Permission on the key       | Areas                                                                                                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **For Products**            | Products, prices, pricelists, images, stock levels, serials, and branding (logos and decoration added to products).                                                  |
| **For Clients**             | Clients, their addresses, and End Users.                                                                                                                             |
| **For Supplier**            | Suppliers.                                                                                                                                                           |
| **For Project**             | Projects, their lines and documents, orders and booking their courier, and Purchase Orders.                                                                          |
| **For Administrative Data** | Reference data such as branches, brands, categories, warehouses, users, sales channels, and webhooks, plus courier quotes, shipments, and branding types and groups. |
| **For OData (PowerBI)**     | Read-only access to OData, for reporting tools.                                                                                                                      |
| **For Rounding**            | Read-only access to the organisation's rounding settings.                                                                                                            |

**Read** lets a key look at data. **Write** lets it create and change data. A few search endpoints use POST but only need **Read**, such as the project search and `POST /api/stocklevel/modifiedAfter`.

The organisation can also hide categories, brands, suppliers, and products from a key. It also chooses the pricelist a key's prices come from, and the branches whose prices it sees. So two keys can see different products and prices. If a product you expect is missing, ask the organisation whether it's hidden from your key.

### When a key doesn't work

A missing or unknown key gets a `401`:

```json
{
  "Success": false,
  "Warnings": [
    {
      "Number": 401,
      "Message": "Unauthorized. A valid X-OrderEazi-Key API key is required. (Reference: 4bf92f3577b34da6a3ce929d0e0e4736)"
    }
  ],
  "Data": null
}
```

A key without the permission an endpoint needs gets a `403`, with the message "Forbidden. Your API key does not have permission to perform this action." Ask the organisation to add the permission to the key.

**Example:** Your shop sync reads products and sends in orders. The organisation gives your key **Read** on **For Products** and **Write** on **For Project**. Later you add a client lookup, and your first call to `/api/client/list` gets a `403`, because the key has no **For Clients** permission. You ask them to add **Read** on **For Clients**.

### Replacing a key

A key works until the organisation deletes it. To replace one, they create a new key, you switch your integration to it, and they delete the old key.

### Related pages

* [Getting started with the API](/central/developers/getting-started-with-the-api.md): your first call
* [Responses, errors, and warnings](/central/developers/responses-errors-and-warnings.md): every error response