Authentifizierung
Die API kennt zwei Wege hinein: das Sitzungs-Cookie der Web-App und einen API-Schlüssel als Bearer-Token. Kommen beide in einer Anfrage, gilt der Bearer.
Bearer-Token
API-Schlüssel gibt es ab dem Plan Pro. Inhaber und Admins legen sie in der
Web-App unter Einstellungen → API-Keys an, auf Wunsch mit Ablaufdatum.
Ein Schlüssel beginnt mit rc_live_ und wird bei der Erstellung genau
einmal vollständig angezeigt. Danach sehen Sie nur noch das Präfix.
Authorization: Bearer rc_live_••••••••Der Schlüssel gehört zu genau einer Organisation, und über ihn lässt sich die
Organisation nicht wechseln. Die API prüft bei jedem Aufruf den Plan: Im Plan
Free ruht ein Schlüssel und jeder Aufruf endet mit 402 plan_upgrade_required. Mit Pro oder Agentur gilt er wieder. Den
MCP-Server gibt es nur im Plan Agentur.
Rechte eines Schlüssels
Ein Schlüssel handelt für die Organisation mit der Rolle Mitglied. Was diese Rolle nicht darf, darf auch kein Schlüssel. Zusätzlich trägt jeder Schlüssel genau eines von drei Rechten:
| Recht | Etikett in der Web-App |
|---|---|
read_only | Nur lesen |
start_scans | Scans starten |
full | Voll |
| Aktion | read_only | start_scans | full |
|---|---|---|---|
| Domains, Läufe, Befunde, Artefakte, Zeitpläne, Kunden und Katalog lesen | ja | ja | ja |
| Nutzung und gebuchte Läufe lesen, auch als CSV (nur ohne Domain-Einschränkung) | ja | nein | ja |
| Läufe starten und abbrechen | nein | ja | ja |
| Domains anlegen und ändern, Nachweis anfordern und prüfen | nein | ja | ja |
| Teilen-Links erstellen | nein | ja | ja |
| Zeitpläne anlegen, ändern und löschen | nein | nein | ja |
| Befunde als behoben markieren, quittieren, Quittierung aufheben | nein | nein | ja |
Reicht das Recht nicht, antwortet die API mit 403 api_key_scope_insufficient. Ein read_only-Schlüssel scheitert damit an
jedem POST, PATCH, PUT und DELETE.
Domain-Einschränkung
Ein Schlüssel lässt sich beim Anlegen auf einzelne Domains beschränken.
Anfragen zu anderen Domains derselben Organisation beantwortet die API dann
mit 404 not_found, damit der Schlüssel nicht verrät, welche Domains es
sonst gibt. Listen zeigen nur die erlaubten Domains.
Die Nutzung und die gebuchten Läufe gelten für die ganze Organisation. Ein
eingeschränkter Schlüssel liest sie nicht, er bekommt dort 403 api_key_scope_insufficient.
Sitzungs-Cookie
Die Web-App benutzt rc_session: HttpOnly, Secure, SameSite=Lax, an die
aktive Organisation des Org-Umschalters gebunden. Für Skripte ist dieser Weg
nicht gedacht. Nehmen Sie einen API-Schlüssel.
Schlüssel schützen
- Legen Sie je Zweck einen eigenen Schlüssel an.
- Geben Sie ihm das kleinste Recht, das reicht, und schränken Sie ihn auf Domains ein, wo es geht.
- Ein widerrufener Schlüssel ist sofort ungültig. Widerrufen Sie im Zweifel und legen Sie einen neuen an.
- Der Schlüssel gehört nie in ein Repository, ein Ticket oder ein Log.