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

# Authentication

All endpoints are authenticated with a per-manufacturer API key passed in the
`X-API-Key` header. Send it on **every** request:

```http theme={"dark"}
X-API-Key: emidat-9f4c1ab7-a7c2f1e9b4d8302c4e6a1f0d9b3e7c2a
```

## Obtaining an API key

API keys are issued per manufacturer and managed by an account **owner**:

1. Log in to the Emidat Platform
2. Navigate to **Settings → Integrations → API Keys** for your manufacturer
3. Click **Create API key**, give it a name, and optionally restrict its **permissions** to specific plants and scopes.
4. Copy the raw key, which is shown **only once** and cannot be retrieved again

## Scopes

A key carries a set of scopes, chosen when it is issued. Each endpoint requires
one; a key without it gets `403`.

| Scope            | Grants                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `view:plants`    | Read plants                                                                                           |
| `view:processes` | Read production processes, and the production figures on a product instance                           |
| `edit:processes` | Write the production figures on a product instance                                                    |
| `view:materials` | Read supplier companies, supplier plants, supplier products, silos, composites, and prechain products |
| `edit:materials` | Create, update, and delete those same entities                                                        |
| `view:products`  | Read product instances and their LCA results                                                          |
| `edit:products`  | Create, update, and delete product instances, and run an LCA                                          |
| `view:recipes`   | Read a BOM, and the per-source impact breakdown of an LCA result                                      |
| `edit:recipes`   | Write a BOM                                                                                           |

A key can never exceed the permissions of the member who issued it. If that
member's role is reduced or their plant access is withdrawn, the key loses the
same ground immediately — the scopes stored on it are capped on every request,
not at issuance.

## Verify your key

`GET /v2/me` reports what the key can do right now. It needs no scope, so any
valid key can call it:

```bash theme={"dark"}
curl https://api.emidat.com/v2/me \
  -H "X-API-Key: emidat-9f4c1ab7-a7c2f1e9b4d8302c4e6a1f0d9b3e7c2a"
```

```json theme={"dark"}
{
  "manufacturer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "api_key_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "owner_profile_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "scopes": ["view:materials", "view:plants"],
  "plant_ids": ["11111111-1111-1111-1111-111111111111"]
}
```

`scopes` and `plant_ids` are the **effective** set, not what was stored at
issuance. An empty `plant_ids` means the key currently reaches no plants. See
[Introspect API key](/api-reference/me/get).

## Authentication errors

| Status             | When                                                                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | No credentials; or the key is malformed, unknown, revoked, or expired. The response is uniform and does not reveal which check failed. |
| `403 Forbidden`    | A valid key lacked the required permission, or targeted a resource outside its access.                                                 |

<Warning>
  Treat the raw key as a secret. Store it in your secrets manager, never in
  source control or logs. If a key is exposed, revoke it and issue a new one.
</Warning>