Token-Köpfe

Jeder Request braucht den passenden Kopf im passenden Header. Falscher Kopf führt häufig zu permission denied oder project not found.

Tabelle: Vier Köpfe

Header	Wert	Wofür	Woher
Token	${ADMIN_TOKEN} aus api/config.yml.env	Collection-Schreibzugriffe (z. B. Content anlegen)	Name token steht im Permission-Schlüssel "token:${ADMIN_TOKEN}" in api/collections/*.yml
X-Auth-Token	JWT aus Login	Projekt anlegen, Reload, User-Requests	POST /api/v1/login mit admin / admin (lokaler Starter-Stack)
X-Admin-Token	Server-Admin-Token	System-APIs wie Projekt-CRUD, Reload	Server-Config des laufenden tibi-servers
Authorization: Bearer …	Gleicher Wert wie X-Admin-Token	Alias für Server-Admin-Token; Deploy-Skripte nutzen ihn am Reload-Endpunkt	Server-Config bzw. api/config.yml.env

Collection schreiben

Dokument anlegen

curl -s -X POST "$URL/api/content" \
  -H "Token: $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hallo"}'

Der Header-Name Token passt zum Schlüssel "token:${ADMIN_TOKEN}" in der Collection-YML (Groß-/Kleinschreibung egal).

Projekt registrieren

JWT holen und Projekt anlegen

jwt=$(curl -s -X POST "$ADMIN_URL/api/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.token')
curl -s -X POST "$SERVER_URL/api/v1/project" \
  -H "X-Auth-Token: $jwt" \
  -H "Content-Type: application/json" \
  -d '{"name":"meinprojekt","configFile":"/data/api/config.yml","enabled":true}'

Zwei Login-Pfade, ein Login

Direkt am Server heißt die Route /api/v1/login (setup.go: Gruppe /api/v1 + /login). Im Starter-Stack proxyt der Admin-Host /api/... auf den Server — deshalb steht im Beispiel $ADMIN_URL/api/login. Beide meinen denselben Login, nur auf verschiedenen Wegen.

Verwechslungs-Fallen

• Projekt-Token ist kein Admin-Token. Token: $ADMIN_TOKEN schreibt Collections, registriert aber keine Projekte. GET /api/v1/project damit antwortet permission denied.
• ADMIN_TOKEN kann keine Projekte anlegen. Nur Sammlungs-Zugriffe plus Reload/Snapshot laut admin.tokens in api/config.yml. Für Projekt-CRUD brauchst du JWT oder Server-Admin-Token.
• Reservierte Namen. x-auth-token, x-admin-token und authorization dürfen nie als Collection-Token-Name in permissions stehen — der Server ignoriert sie dort fail-closed (internal/models/permission.go).
• Query statt Header geht auch. Collection-Token akzeptiert der Server zusätzlich als Query-Parameter mit gleichem Namen. Nutze das nur zum Testen, nie im Produktiv-Frontend.

Fehlermeldungen

Antwort	Ursache	Fix
permission denied: admin token lacks permission project.read	Collection-Token an System-API gesendet	JWT via X-Auth-Token oder X-Admin-Token nehmen
permission denied (403)	Kopf fehlt oder Wert falsch	Header-Namen und .env-Wert prüfen
project not found (404)	Projekt im laufenden Server nicht registriert	Per JWT registrieren, dann Reload

Nicht mischen

Ein funktionierender Collection-Token beweist keinen Projekt-Admin-Zugriff. Prüfe jeden Kopf an seinem eigenen Endpunkt.

Verifiziert am e3f92eb 2026-10-14 (tibi-svelte-starter) und 68b4278 2026-10-15 (tibi-server)