System-Routen

Neben dem Collection-CRUD (/api/v1/_/:project/:collection) verwaltet der Server System-Objekte direkt unter /api/v1/. Jedes dieser fünf Modelle hat dieselben fünf Routen; dazu kommen Meta- und Scope-Routen.

Routen-Tabelle

Methode + Pfad	Zweck	Rechte
GET /api/v1/user, POST /api/v1/user, GET /api/v1/user/:id, PUT /api/v1/user/:id, DELETE /api/v1/user/:id	Nutzer anlegen, lesen, ändern, löschen (Passwort nie in Antworten)	Nutzer-Scope (z. B. user.read) bzw. Admin-Token; Org-/Team-Zugehörigkeit schränkt ein
GET /api/v1/project, POST /api/v1/project, GET /api/v1/project/:id, PUT /api/v1/project/:id, DELETE /api/v1/project/:id	Projekte registrieren und konfigurieren	Projekt-Scope (z. B. project.read); Fremd-Orgs sind unsichtbar
GET /api/v1/org, POST /api/v1/org, GET /api/v1/org/:id, PUT /api/v1/org/:id, DELETE /api/v1/org/:id	Mandanten (Orgs) verwalten	Org-Scope (z. B. org.read); nur eigene Org
GET /api/v1/team, POST /api/v1/team, GET /api/v1/team/:id, PUT /api/v1/team/:id, DELETE /api/v1/team/:id	Gruppen in einer Org verwalten	Team-Scope (z. B. team.read)
GET /api/v1/token, POST /api/v1/token, GET /api/v1/token/:id, PUT /api/v1/token/:id, DELETE /api/v1/token/:id	Eigene Personal-Access-Tokens (PAT) verwalten	Login-Sitzung nötig — ein PAT darf nicht seine eigene Verwaltung aufrufen
GET /api/v1/token/_scopes	Katalog aller Scopes, die du aktuell vergeben darfst (gleiche Quelle wie die Anlage-Prüfung)	Nur Nutzer-Login (X-Auth-Token bzw. Session-Cookie); PAT → 403
GET /api/v1/_meta	Feld-Metadaten aller System-Modelle als {models: {user: […], …}}	Wie die Modell-Routen (System-Ebene)
GET /api/v1/_meta/<modell>	Feld-Metadaten eines Modells (user, project, org, team, token)	Wie oben

Die fünf CRUD-Routen je Modell entstehen in internal/dbapi/register.go (GET /:id, GET, POST, PUT /:id, DELETE /:id); die Meta-Routen legt AddMetaRoute an. POST /api/v1/login (JWT holen) und POST /api/v1/_/:project/_/admin/… (Reload, Suche, Backup) gehören ebenfalls zur System-Ebene — siehe Rechte und Tokens und Betrieb.

Projekt lesen (Nutzer-Login)

GET /api/v1/project
X-Auth-Token: <jwt>

Token mit engem Scope anlegen

POST /api/v1/token
X-Auth-Token: <jwt>
{"name": "lese-job", "scopes": ["namespace.meinprojekt.content.read"]}
# Antwort enthält einmalig: {"token": "tibi_pat_<id>_<secret>", …}
# Danach nur noch: userId, name, scopes, expiresAt, lastUsedAt — nie das Secret.

Vergebbare Scopes abfragen

GET /api/v1/token/_scopes
X-Auth-Token: <jwt>
# ["audit.read", "llm.chat", "namespace.meinprojekt", "namespace.meinprojekt.content.read", "project.read", "user.read", …]

Achtung

Das Klartext-Secret (token-Feld, Format tibi_pat_<id>_<secret>) steht nur in der Anlage-Antwort. Gespeichert wird nur ein SHA-256-Hash (tokenHash); Anzeige-Prefix (tokenPrefix) und lastUsedAt dienen der Wiedererkennung. expiresAt leer heißt: kein Ablauf.

_meta: Was steckt drin

Jeder Eintrag beschreibt ein Struct-Feld — erzeugt aus den Go-Tags (getModelMeta, getStructMeta):

Schlüssel	Inhalt	Beispiel (token-Modell)
name	JSON-Feldname	userId, name, scopes, expiresAt, lastUsedAt (tokenHash ist -, token nur lesend)
type / kind	Typname / Art	string, slice
validator	Validierungsregeln, falls gesetzt	["required", "min=1", "max=100"] bei name
sliceOf / structOf	Elementtyp bei Listen bzw. Unterfelder bei Objekten	scopes: sliceOf: string

Für Generatoren und Agents: GET /api/v1/_meta/token nennt die Felder, die POST /api/v1/token akzeptiert — etwa dass scopes eine String-Liste ist.

Verifiziert am 68b4278 2026-10-17 (tibi-server)