Authentifizierung & Scopes
Wie API-Keys, Bearer-Token, Scopes und Projekt-Einschränkungen funktionieren.
Als Markdown ansehenJede 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. Ein Key sieht aus wie aclipp_live_... und wird nur einmal vollständig angezeigt, beim Erstellen. Sende ihn bei jeder Anfrage als Bearer-Token:
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:
:readgewährt Lesezugriff auf eine Ressource.:writeerlaubt 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.