# Authentifizierung & Scopes

Wie API-Keys, Bearer-Token, Scopes und Projekt-Einschränkungen funktionieren.

Jede Anfrage an einen authentifizierten Endpunkt der aclipp API benötigt einen API-Key. Der Key identifiziert den Workspace, den Nutzer und genau das, was die Anfrage tun darf. Das generierte OpenAPI-Schema unter `/api/v1/openapi.json` ist öffentlich und benötigt keinen Key.

## API-Keys

Erstelle und widerrufe Keys in den [Workspace-Einstellungen](https://app.aclipp.com/settings/api). Ein Key sieht aus wie `aclipp_live_...` und wird nur einmal vollständig angezeigt, beim Erstellen. Sende ihn bei jeder Anfrage als Bearer-Token:

```
Authorization: Bearer aclipp_live_...
```

Der Workspace wird durch den Key impliziert und taucht deshalb nie in der URL auf. Das Widerrufen eines Keys greift innerhalb von etwa einer Minute.

## Scopes

Jeder Key erhält eine Menge an Scopes und kann nur das tun, was diese erlauben. Scopes folgen dem Muster `resource:action`:

- `:read` gewährt Lesezugriff auf eine Ressource.
- `:write` erlaubt Erstellen, Ändern und Löschen.

| Scope                                  | Erlaubt                                                      |
| -------------------------------------- | ------------------------------------------------------------ |
| `projects:read` / `projects:write`     | Projekte lesen / verwalten                                   |
| `clippings:read` / `clippings:write`   | Clippings lesen / verwalten                                  |
| `outlets:read` / `outlets:write`       | Den Outlet-Katalog des Workspace lesen / verwalten           |
| `reports:read` / `reports:write`       | Reports lesen / verwalten                                    |
| `dashboards:read` / `dashboards:write` | Dashboards lesen / verwalten                                 |
| `analytics:read`                       | Analyse-Katalog lesen und aggregierte Analysen abfragen      |
| `ai-visibility:read`                   | KI-Sichtbarkeits-Chats, Source-Domains und Source-URLs lesen |

Gib einem Key nur die Scopes, die er braucht. Ein Reporting-Skript bekommt zum Beispiel vielleicht `reports:read` und sonst nichts. Eine Anfrage, der ein erforderlicher Scope fehlt, wird mit `403 FORBIDDEN` abgelehnt.

## Projekt-Einschränkungen

Ein Key kann optional auf bestimmte Projekte beschränkt werden. Ein eingeschränkter Key kann projektbezogene Ressourcen nur innerhalb seiner Projekte lesen oder schreiben; alles außerhalb wird als „nicht gefunden“ behandelt.

Outlets gehören zum Workspace und nicht zu einem einzelnen Projekt. Ein projektbeschränkter Key muss beim Lesen von Outlets eine seiner erlaubten Projekt-IDs angeben. Der Outlet-Katalog bleibt workspaceweit sichtbar, während `clippingsCount` nur für dieses Projekt berechnet wird. Outlet-Änderungen erfordern einen uneingeschränkten Key.

## Fehler

Fehler bei Authentifizierung und Autorisierung nutzen das Standard-Fehlerformat:

- `401` — fehlender, ungültiger oder widerrufener Key.
- `403` — der Key ist gültig, hat aber nicht den erforderlichen Scope.
- `404` — die Ressource existiert nicht oder liegt außerhalb der Projekt-Einschränkung des Keys.

Den erforderlichen Scope für jeden Endpunkt findest du in der [API-Referenz](/docs/api-reference).