Authentifizierung mit API-Key

REST-API und MCP-Server erwarten bei jedem Aufruf einen API-Key im Header. Cookies, Sessions und OAuth unterstützen die Schnittstellen nicht.

Authorization: Bearer IHR_API_KEY

Ein Key, eine Marke

Jeder Key gehört zu genau einer Marke. Brandhub liest die Marke aus dem Key, nie aus URL oder Parameter. Auf Datensätze einer anderen Marke antwortet die API mit 404. Rufen Sie die API trotzdem unter der Subdomain Ihrer Marke auf, damit Logs und Konfiguration zusammenpassen.

Rechte

Ein Key trägt read, write oder beide. write schließt read nicht ein.

Recht	Erlaubt
read	alle lesenden Endpunkte und MCP-Tools
write	Seiten und Blöcke anlegen, ändern und löschen, Corporate Language pflegen
read + write	nötig für jede schreibende Integration

Mit nur write antworten lesende REST-Endpunkte mit 403. Lesende MCP-Tools melden einen Tool-Fehler.

Key erhalten und widerrufen

1. Ihr Brand Success Management schaltet die API für Ihre Marke frei.
2. Es legt einen Key mit Namen, Rechten und Gültigkeit an. Zur Wahl stehen 30 Tage, 90 Tage, ein Jahr oder unbegrenzt bis zum Widerruf.
3. Der Key erscheint einmal im Klartext. Brandhub speichert ihn nicht lesbar.
4. Jeder Aufruf aktualisiert „Zuletzt genutzt“ am Key. Anlage und Widerruf stehen im Audit-Log der Marke, Schreibvorgänge in der Versionshistorie der Seite.
5. Brauchen Sie einen Key nicht mehr, lassen Sie ihn widerrufen. Er ist ab dann ungültig.

Umgang mit dem Key

• Legen Sie den Key nie in Browser-Code, Apps oder ein Repository. Mit dem Key liest jede Person die Daten Ihrer Marke, mit write ändert sie sie.
• Geben Sie pro Integration einen eigenen Key aus. So widerrufen Sie Zugänge einzeln und ordnen „Zuletzt genutzt“ zu.
• Vergeben Sie write erst, wenn eine Integration schreiben soll. Änderungen erscheinen sofort im Portal. Brandhub versioniert sie, im Backend lassen sie sich zurücksetzen.

Fehlercodes

Fehler kommen als JSON mit einer lesbaren message. Validierungsfehler enthalten zusätzlich errors je Feld.

Status	Bedeutung	Abhilfe
401	Key fehlt, ungültig, widerrufen oder abgelaufen	Header prüfen (Bearer, Leerzeichen, Key)
403	API für die Marke nicht freigeschaltet	Freischaltung bei Ihrem Brand Success Management anfragen
403	Recht fehlt, z. B. nur read beim Schreiben (REST)	Key mit read + write verwenden
404	Datensatz existiert nicht oder gehört zu einer anderen Marke	ID prüfen
422	Validierung fehlgeschlagen, z. B. Pflichtfeld fehlt, Block-Typ unbekannt	Feld errors der Antwort lesen
429	Rate-Limit überschritten	Retry-After abwarten, siehe Limits

{
  "message": "Das Feld title muss ausgefüllt sein.",
  "errors": { "title": ["Das Feld title muss ausgefüllt sein."] }
}

Der MCP-Server liefert bei fehlendem Key, fehlender Freischaltung und Rate-Limit dieselben HTTP-Status. Ein fehlendes Recht meldet er als Tool-Fehler, etwa wenn ein Key ohne write append_block aufruft.