# Authentifizierung & Scopes

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

Jede Anfrage an einen authentifizierten Endpunkt der öffentlichen aclipp API benötigt einen API-Key. OAuth-Access-Tokens authentifizieren MCP-Verbindungen; den Ablauf findest du unter [KI-Agenten mit MCP verbinden](/docs/mcp). Der Zugangsnachweis identifiziert den Workspace, den Nutzer und genau das, was die Anfrage tun darf.

## 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.

## OAuth-Access-Tokens

OAuth-Access-Tokens authentifizieren MCP-Verbindungen, nicht Anfragen an die Public API. Registrierte OAuth-Clients erhalten ein Access-Token, nachdem du die Verbindung im Browser freigegeben hast. Der Client sendet dieses Token im selben Bearer-Header und verwaltet es für dich:

```
Authorization: Bearer <OAuth-Access-Token>
```

Ein OAuth-Access-Token enthält die Scopes und die optionale Projekt-Einschränkung, die dieser MCP-Verbindung gewährt wurden.

## Scopes

Jeder Zugangsnachweis 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                                                                     |
| `prompts:read` / `prompts:write`           | KI-Sichtbarkeits-Prompts und Prompt-Themen lesen / verwalten                                   |
| `clippings:read` / `clippings:write`       | Clippings lesen / verwalten                                                                    |
| `outlets:read` / `outlets:write`           | Den Outlet-Katalog des Workspace lesen / verwalten                                             |
| `authors:read` / `authors:write`           | Autoren lesen; Schreibzugriff ist für Autorenänderungen reserviert                             |
| `reports:read` / `reports:write`           | Reports lesen / verwalten                                                                      |
| `dashboards:read` / `dashboards:write`     | Dashboards lesen / verwalten                                                                   |
| `integrations:read` / `integrations:write` | Integrationen eines Projekts lesen / verwalten; API-Keys lassen sich nicht über die API setzen |
| `analytics:read`                           | Analyse-Katalog lesen und aggregierte Analysen abfragen                                        |
| `ai-visibility:read`                       | KI-Sichtbarkeits-Chats, Source-Domains und Source-URLs lesen                                   |

Gib einem Zugangsnachweis 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 API-Key oder eine OAuth-Verbindung kann optional auf bestimmte Projekte beschränkt werden. Ein eingeschränkter Zugangsnachweis 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 Zugangsnachweis 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 Zugangsnachweis.

## Fehler

Fehler bei Authentifizierung und Autorisierung nutzen das Standard-Fehlerformat:

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

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