Öffentliche API-Authentifizierung & API-Schlüssel

Die öffentliche Ottili ONE Developer API* ist der freigegebene, dokumentierte Entwickler-Vertrag für Ottili ONE. Sie ist von der internen Unified API getrennt: Nur die Endpunkte unter dem öffentlichen Basis-Pfad sind für externe Entwickler gedacht, interne Admin-, Debug- und Lokale-Entwicklung-Routen gehören nie zu dieser Oberfläche.

Diese Anleitung behandelt alles, was du für die Authentifizierung und Verwaltung von API-Schlüsseln brauchst: Account- und Unternehmensvoraussetzungen, Erstellen eines Schlüssels, sichere Speicherung, Request-Header, Scopes, Rotation, Widerruf, Umgebungen und die häufigsten Fehler.

Die Developer API befindet sich im Public Beta*. Endpunktpfade und Scopes sind stabil, aber Limits und Metadaten können sich weiterentwickeln. Der Live-Endpunkt GET /api/v1/developer ist die Quelle der Wahrheit für die aktuelle Version, den Status und den Endpunkt-Index.

1. Basis-URL

Alle öffentlichen Developer-API-Endpunkte werden über den öffentlichen Host und Basis-Pfad bereitgestellt:

https://api.ottilione.com/api/v1/developer

Diese Oberfläche dokumentiert nur den öffentlichen Entwickler-Vertrag. Interne Unified-API-Routen, Admin-Endpunkte, Dashboard-Routen und Lokale-Entwicklung-Pfade gehören bewusst nicht* zu dieser Oberfläche.

2. Account- und Unternehmensvoraussetzungen

Bevor du API-Schlüssel erstellen kannst, benötigst du:

• Einen verifizierten Ottili-User-Account* (siehe [Account & Login](/docs/account-and-login)).
• Eine Mitgliedschaft in einem aktiven oder Test-Unternehmen* (siehe [Unternehmen & Team](/docs/company-and-team)). Das Unternehmen darf nicht suspendiert oder archiviert sein.
• Einen aktiven Workspace* innerhalb dieses Unternehmens (nicht suspendiert oder archiviert) — siehe [Workspaces & Module](/docs/workspace-and-modules).
• Eine Rolle, die die Developer API nutzen darf: eine developer-/platform-developer-/platform-admin-Rolle, ein Company-Owner oder Company-Admin oder ein Superadmin.

API-Schlüssel sind an deine User-Mitgliedschaft gebunden*. Es sind keine frei schwebenden Zugangsdaten: Jeder Schlüssel löst auf den Unternehmens- und Workspace-Kontext des erstellenden Users auf. Schlüssel können zudem nicht verwendet werden, um andere Schlüssel zu verwalten — das Erstellen, Auflisten, Widerrufen oder Rotieren eines Schlüssels erfordert immer einen User-Token*, nie einen anderen API-Schlüssel.

3. Einen Request authentifizieren

Jeder authentifizierte Request sendet den Schlüssel im Standard-Authorization-Header:

Authorization: Bearer ott_your_api_key_here

Zwei Credential-Typen werden akzeptiert:

• API-Schlüssel* — mit dem Präfix ott_, bei der Erstellung nur einmal angezeigt, im Ruhezustand gehasht gespeichert.
• JWT-Bearer-Tokens* — von Ottili Auth für User-Sessions ausgestellt (für die Schlüsselverwaltung selbst verwendet).

Wenn ein Request ein anderes Unternehmen oder einen anderen Workspace als den Standard des Schlüssels benötigt, wählst du diesen über Header (aufgelöst aus der verifizierten Mitgliedschaft des Schlüssels):

X-Platform-Company: your-company-slug
X-Platform-Workspace: your-workspace-slug

Entsprechende Query-Parameter (company_slug, workspace_slug) sind ebenfalls erlaubt. Rohe numerische Company-ID-Header werden ignoriert* — die API löst den Kontext aus der verifizierten Mitgliedschaft auf, nie aus einem nicht vertrauenswürdigen Header.

Ein fehlendes oder ungültiges Credential führt geschlossen zu einem 401.

Beispiel: Module deines Unternehmens auflisten

curl "https://api.ottilione.com/api/v1/developer/modules" \
  -H "Authorization: Bearer ott_your_api_key_here" \
  -H "X-Platform-Company: your-company-slug" \
  -H "X-Platform-Workspace: your-workspace-slug"

4. Scopes

Schlüsseln werden Scopes* gewährt, die einschränken, was sie dürfen. Fordere nur die Scopes an, die deine Integration benötigt.

Ein Request, dessen Schlüssel den benötigten Scope nicht hat, wird mit 403 und dem Code DEVELOPER_SCOPE_REQUIRED abgelehnt. Das Wildcard * matcht jeden Scope in einer Gruppe (z. B. matcht module:* auf module:execute).

5. Einen API-Schlüssel erstellen

Die Schlüsselerstellung erfordert einen User-Token* (keinen API-Schlüssel) sowie den Admin*-Scope in einem aktiven Unternehmenskontext.

curl -X POST "https://api.ottilione.com/api/v1/developer/api-keys" \
  -H "Authorization: Bearer <user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "scopes": ["developer:read", "module:execute"],
    "expires_days": 90
  }'

Request-Body:

• name (erforderlich, 1–100 Zeichen): ein lesbares Label, z. B. Production Integration.
• scopes (optional): Liste von Scopes; leer bedeutet standardmäßig nur Lesezugriff.
• expires_days (optional, 1–365): Ablauf in Tagen. Weglassen für einen Schlüssel ohne Ablauf.

Antwort (der rawKey wird nur einmal* angezeigt):

{
  "keyId": 123,
  "rawKey": "ott_example_api_key_xyz123",
  "keyPrefix": "ott_",
  "name": "Production Integration",
  "scopes": ["developer:read", "module:execute"],
  "role": "developer",
  "expiresAt": "2026-08-15T00:00:00Z",
  "createdAt": "2026-05-15T00:00:00Z"
}

Kopiere den rawKey sofort. Er wird nie wieder zurückgegeben — das Auflisten von Schlüsseln liefert nur Präfix und Metadaten.

6. Schlüssel sicher speichern

Behandle einen API-Schlüssel wie ein Passwort:

• Kopiere ihn bei der Erstellung.* Der rohe Schlüssel wird nur einmal angezeigt und kann nicht wiederhergestellt werden.
• Verwende einen Secret-Manager.* Speichere ihn in Umgebungsvariablen, einem Vault oder deinem CI-Secret-Store — nie in der Versionskontrolle, Client-Code, Logs oder Chat.
• Scope eng fassen.* Gewähre die minimalen Scopes, die deine Integration benötigt (siehe [Rollen & Berechtigungen](/docs/roles-and-permissions)).
• Setze Ablaufdaten* für Schlüssel, die nicht ewig leben müssen.
• Bei Leckage rotieren.* Wenn ein Schlüssel möglicherweise offengelegt wurde, widerrufe oder rotiere ihn sofort (Abschnitte 8–9).

7. Deine Schlüssel auflisten

curl "https://api.ottilione.com/api/v1/developer/api-keys" \
  -H "Authorization: Bearer <user-jwt>"

Liefert jeden von dir besitzten Schlüssel mit Präfix, Name, Scopes, Aktiv-Zustand, Ablauf und letzter Nutzung. Rohe Schlüssel sind nie enthalten.

8. Einen Schlüssel rotieren

Rotation stellt einen neuen Schlüssel mit denselben Scopes und demselben Ablauf* aus und widerruft dann sofort den alten. Damit kannst du Credentials erneuern, ohne die Scope-Konfiguration zu ändern.

curl -X POST "https://api.ottilione.com/api/v1/developer/api-keys/123/rotate" \
  -H "Authorization: Bearer <user-jwt>"

Die Antwort enthält einen neuen rawKey (nur einmal angezeigt) und revokedKeyId, der auf den alten Schlüssel zeigt. Aktualisiere deine Integration auf den neuen Schlüssel und nimm den alten außer Betrieb — der alte Schlüssel funktioniert nicht mehr, sobald die Rotation abgeschlossen ist.

9. Einen Schlüssel widerrufen

Widerruf deaktiviert einen Schlüssel dauerhaft*. Das kann nicht rückgängig gemacht werden; ein widerrufener Schlüssel ist weg und es muss ein neuer erstellt werden.

curl -X DELETE "https://api.ottilione.com/api/v1/developer/api-keys/123" \
  -H "Authorization: Bearer <user-jwt>"

Der Widerruf wird auditiert. Nur Schlüssel, die dir gehören, können widerrufen werden, und nur mit User-Token plus Admin-Scope.

10. Umgebungen

Die öffentliche Developer API wird über eine einzige Production-Oberfläche* bereitgestellt (Public Beta). Es gibt im freigegebenen öffentlichen Vertrag keinen separaten Sandbox- oder Staging-Host, daher solltest du nicht unterschiedliche Basis-URLs pro Umgebung hartkodieren.

Um Umgebungen in deinen eigenen Systemen zu trennen:

• Erstelle pro Umgebung einen eigenen Schlüssel* (z. B. Staging Sync, Production Sync) mit eigenem Namen und minimalen Scopes.
• Halte Production-Credentials aus nicht-Production-Deployments heraus.
• Bevorzuge Rotation* statt langlebiger gemeinsamer Schlüssel beim Promoten zwischen Umgebungen.

11. Rate Limits

• Öffentliche Discovery*-Endpunkte (Index und öffentlicher Katalog) erlauben 120 Requests pro 60 Sekunden pro Client-IP.
• Authentifizierte* Endpunkte sind pro Schlüssel/Identität ratelimitiert. Beim Überschreiten antwortet die API mit 429 Too Many Requests und einem Retry-After-Header, der angibt, wie viele Sekunden gewartet werden soll.

Gehe zurück und wiederhole nach Retry-After; führe keine enge Schleife bei 429 aus.

12. Häufige Fehler

Jede Fehlerantwort enthält einen maschinenlesbaren code, eine menschenlesbare message und eine requestId, die du für das Tracing mit dem Support teilen kannst.

Verwandt

• Die OpenAI-kompatible [Ottili AI API](/docs/ottili-ai-api) verwendet dasselbe ott_-Schlüsselformat für Model-Calls.
• Verwalte deinen [Account & Login](/docs/account-and-login), [Unternehmen & Team](/docs/company-and-team) und [Workspaces & Module](/docs/workspace-and-modules).