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

# Authentifizierung & API-Schlüssel

> Mit cx-api-key authentifizieren, Scopes und Least-Privilege für Agenten.

Alle Public-API-Requests brauchen einen API-Schlüssel im HTTP-Header `cx-api-key`:

```
cx-api-key: dein-api-schlüssel
```

Ohne gültigen Schlüssel erhältst du `401` mit Code `API_KEY_REQUIRED` oder `INVALID_API_KEY`.

## Schlüssel erstellen und verwalten

Schlüssel legst du unter [Einstellungen → API](https://armin.cx/app/_/settings/api) an. Jeder Schlüssel gehört zu einer Organisation — mit einem Schlüssel kommst du nicht in einen anderen Workspace.

| Aktion              | Wo                                                |
| ------------------- | ------------------------------------------------- |
| Schlüssel erstellen | Einstellungen → API → **API-Schlüssel erstellen** |
| Rotieren            | Neuen Schlüssel anlegen, deployen, alten löschen  |
| Widerrufen          | Einstellungen → API → Schlüssel löschen           |

<Tip>
  Benenne Schlüssel nach Zweck (`prod-warehouse-sync`, `staging-ki-agent`), damit du bei der Rotation weißt, welche Integration du anpasst.
</Tip>

## Scopes

Scopes begrenzen, was ein Schlüssel darf. Neue Schlüssel haben standardmäßig nur **`tickets:read`**.

| Scope            | Berechtigung (v1)                                                                    |
| ---------------- | ------------------------------------------------------------------------------------ |
| `tickets:read`   | `GET /public/v1/tickets`, `/tickets/:n`, `/tickets/:n/messages`, `/views`, `/health` |
| `tickets:write`  | Legacy `POST /public/tickets` (Ticket erstellen)                                     |
| `tickets:export` | Legacy `POST /public/tickets/export`                                                 |
| `analytics:read` | Legacy Statistik- und Agenten-Metriken-Endpoints                                     |

Fehlt der Scope, kommt **`403`** mit Code `FORBIDDEN_SCOPE`.

### Least Privilege für KI-Agenten

Für reine Lese-Agenten (Tickets listen, Threads lesen, zusammenfassen):

1. Schlüssel nur mit **`tickets:read`** anlegen.
2. `tickets:write` und `tickets:export` nur geben, wenn der Agent Legacy-Schreib-/Export-Endpoints braucht.
3. Schlüssel mit einem Agenten verknüpfen, wenn die sichtbaren Ansichten den Posteingang-Berechtigungen dieses Agenten entsprechen sollen (siehe unten).

### Legacy-Schlüssel ohne Scopes

Ältere Schlüssel ohne befüllte `scopes`-Spalte behalten während des Migrationsfensters **vollen Zugriff**. Beim Rotieren neue Schlüssel mit expliziten Scopes verwenden.

## Agent-verknüpfte Schlüssel und Ansichtszugriff

Ist ein API-Schlüssel mit einem Support-Agenten verknüpft:

* **`GET /views`** liefert nur Ansichten, die dieser Agent im Posteingang sieht.
* **`GET /tickets?view_id=...`** liefert **`404 VIEW_NOT_FOUND`**, wenn der Agent die Ansicht nicht sehen darf.

Service-Schlüssel **ohne** verknüpften Agenten sehen alle Organisations-Ansichten.

<Warning>
  Findet deine Integration eine Ansicht nicht, die in der UI existiert, prüfe, ob der Schlüssel agent-verknüpft ist und ob der Agent die Freigaberegeln der Ansicht erfüllt.
</Warning>

## Sicherheit

* API-Schlüssel nie in Client-Code, öffentlichen Repos oder Browser-Extensions.
* Bei Leak sofort rotieren.
* Getrennte Schlüssel pro Umgebung (Staging vs. Produktion).
* Scoped Schlüssel statt Legacy-Vollzugriff bevorzugen.

## Verwandt

* [Erste Schritte](/de/api/getting-started)
* [Fehler](/de/api/errors) — u. a. `FORBIDDEN_SCOPE`