Authentifizierung & Scopes

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. 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. Ein Key sieht aus wie aclipp_live_... und wird nur einmal vollständig angezeigt, beim Erstellen. Sende ihn bei jeder Anfrage als Bearer-Token:

Text

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:

Text

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