API-Tokens und erlaubte Herkünfte

Worum es geht

Ein API-Token ist der Schlüssel, mit dem Ihre Website, die Kommandozeile hcms oder ein anderes System die Content API nutzt. Jedes Token hat eigene Berechtigungen und lässt sich auf Collections und eine Umgebung beschränken. Legen Sie für jeden Zweck ein eigenes Token an – dann können Sie eines widerrufen, ohne alles andere zu stören.

Voraussetzungen

Recht API-Tokens verwalten. Sie finden die Tokens unter API-Tokens im Abschnitt Entwickler oder unter Einstellungen.

Ein Token erstellen

1. Klicken Sie auf Token erstellen.
2. Geben Sie einen Name ein, z.B. „Website Produktion“.
3. Schalten Sie unter Berechtigungen nur ein, was gebraucht wird:

Berechtigung	Erlaubt
Lesen	Inhalte abrufen: Collections, Einträge, Seiten, Menüs, Theme, Medien, Suche, Einstellungen. Nötig auch für die öffentlichen Aufrufe mit ?site=
Schreiben	Einträge anlegen, ändern und löschen
Veröffentlichen	Einträge beim Anlegen oder Ändern auf „veröffentlicht“ setzen
Vorschau	Entwürfe lesen und Vorschau-Links prüfen
Verwaltung	Struktur ändern über die Management-API: Collections, Blöcke, Layouts, Theme, Seiten, Menüs, Formulare, Medien-Upload, Umgebungen (die Kommandozeile hcms braucht das für push)

4. Collection-Beschränkung: Markieren Sie Collections, wenn das Token nur diese sehen soll. Leer = alle Collections.
5. Umgebung: Alle Umgebungen oder eine bestimmte Umgebung. Ein gebundenes Token sieht immer nur diese Umgebung.
6. Rate-Limit / Min. (optional): Höchstzahl Anfragen pro Minute. Ohne Angabe gelten 600 Anfragen pro Minute für das Abrufen und 60 pro Minute für die Management-API.
7. Läuft ab am (optional): Ab dem Folgetag ist das Token ungültig.
8. Klicken Sie auf Erstellen.

Es erscheint Token erstellt mit dem vollständigen Token. Kopieren Sie es jetzt und bewahren Sie es sicher auf – Scorebase speichert nur eine Prüfsumme und kann es nie wieder anzeigen. Schliessen Sie mit Fertig.

Aufbau eines Tokens

hcms_live_ab12cd34.0123456789abcdef0123456789abcdef
└──── Präfix ────┘ └────────── Geheimteil ──────────┘

• Der Präfix (Teil vor dem Punkt) steht in der Liste in der Spalte Präfix. Er ist nicht geheim und dient als öffentliche Kennung für Aufrufe aus dem Browser (?site=hcms_live_ab12cd34).
• Das ganze Token ist geheim. Es gehört nur auf Server, nie in Browser-Code, nie in ein Git-Repository.

Ihre Website sendet das Token bei jeder Anfrage so mit:

Authorization: Bearer hcms_live_ab12cd34.0123456789abcdef0123456789abcdef

Die Tokenliste

Die Tabelle zeigt Name, Präfix, Berechtigungen, Herkünfte, Zuletzt verwendet, Läuft ab, Status (Aktiv oder Widerrufen) und das Papierkorb-Symbol zum Widerrufen.

Widerrufen: Das Token wird sofort ungültig; Anwendungen, die es nutzen, verlieren den Zugriff. Das lässt sich nicht rückgängig machen.

Berechtigungen, Umgebung und Ablauf eines bestehenden Tokens lassen sich nicht ändern. So tauschen Sie ein Token ohne Ausfall aus:

1. Neues Token mit den gewünschten Einstellungen erstellen.
2. Das neue Token in Ihrer Website hinterlegen und die Website neu ausliefern.
3. Prüfen, dass beim alten Token Zuletzt verwendet stehen bleibt.
4. Das alte Token widerrufen.

Erlaubte Herkünfte

Aufrufe aus dem Browser – Formulare absenden, Seitenaufrufe und Klicks zählen, Tickets reservieren und kaufen – laufen ohne geheimes Token über den öffentlichen Präfix (?site=). Weil der Präfix im Quelltext Ihrer Website steht, legt die Liste der erlaubten Herkünfte fest, von welchen Websites er benutzt werden darf.

1. Klicken Sie in der Spalte Herkünfte auf den Eintrag des Tokens (beliebig mit Warnsymbol oder die Anzahl).
2. Im Fenster Erlaubte Website-Herkünfte tragen Sie unter Adresse hinzufügen die Adresse Ihrer Website ein, z.B. https://www.beispiel.ch: nur Schema und Host, ohne Pfad. Fehlt https://, wird es ergänzt. Höchstens zwanzig Einträge.
3. Tragen Sie jede Variante ein, unter der die Website erreichbar ist (mit und ohne www, Test-Adresse).
4. Klicken Sie auf Speichern.

So wirkt die Liste:

Liste	Lesen mit ?site= (z.B. Formular laden, Eventliste)	Schreiben mit ?site= (Formular absenden, Zählung, Reservierung, Kauf)
leer	von jeder Website	abgewiesen (403 ORIGIN_NOT_ALLOWED)
gefüllt	nur von den eingetragenen Adressen	nur von den eingetragenen Adressen

Für Tokens, die nur auf einem Server laufen (mit Authorization-Kopfzeile), spielt die Liste keine Rolle.

Empfohlene Tokens

Zweck	Berechtigungen	Umgebung	Herkünfte
Live-Website (Server)	Lesen, bei Bedarf Vorschau	Produktion	–
Öffentlicher Präfix der Live-Website	Lesen	Produktion	Adressen der Website
Lokale Entwicklung	Lesen, Vorschau	Test-Umgebung	http://localhost:3000 bei Bedarf
Kommandozeile, Deployment	Verwaltung, Lesen	Test-Umgebung	–
Anbindung, die Einträge schreibt	Schreiben, bei Bedarf Veröffentlichen, eingeschränkt auf die nötigen Collections	passend	–

Wenn etwas nicht klappt

Fehler	Ursache	Lösung
401 UNAUTHORIZED	Kopfzeile fehlt oder ist falsch, Token unvollständig kopiert	Genau Authorization: Bearer <token> senden; Token vollständig kopieren
401 TOKEN_INACTIVE	Token widerrufen	Neues Token erstellen
401 TOKEN_EXPIRED	Ablaufdatum erreicht	Neues Token erstellen
403 FORBIDDEN	Dem Token fehlt die nötige Berechtigung (z.B. Schreiben oder Vorschau)	Token mit passender Berechtigung erstellen
403 ORIGIN_NOT_ALLOWED	Aufruf aus dem Browser, Herkunft nicht eingetragen	Adresse unter Herkünfte eintragen
404 NOT_FOUND bei einer Collection	Die Collection steht nicht in der Collection-Beschränkung des Tokens, das Token ist an eine andere Umgebung gebunden, oder API aktiv ist aus	Beschränkung und Umgebung des Tokens sowie den Schalter API aktiv prüfen
429 RATE_LIMIT_EXCEEDED	Zu viele Anfragen pro Minute	Die Sekunden aus der Kopfzeile Retry-After abwarten; Antworten zwischenspeichern

Weiterlesen

• Eigene Website anbinden
• Content API: Inhalte abrufen