API-Token

Ein API-Token ermöglicht es einer Drittsoftware, die API-Endpunkte von Omniscol im Namen der Schule aufzurufen — lesend und, wenn schreibende API-Endpunkte ausgewählt sind, auch schreibend.

Das ist mächtig — also mit Sorgfalt zu handhaben.

Generierung

Ein Token wird in Teilen (Import/Export > Teilen) generiert. Sie geben an:

• einen Schlüssel (in Omniscol generiert, mit Bezeichnung und eventuellem Ablauf; sein Ablaufdatum kann später geändert werden),
• einen Geltungsbereich: die Liste der API-Endpunkte, die dieses Token aufrufen darf (gewähren Sie nur, was unbedingt erforderlich ist),
• optional einen Ablauf des Tokens. Dieses Datum wird in das generierte JWT eingetragen und kann danach nicht mehr geändert werden.

Das Löschen des Schlüssels oder das Erreichen seines Ablaufs widerruft sofort die abgeleiteten Token. Um den Ablauf eines einzelnen Tokens zu ändern, generieren Sie ein neues JWT.

Verwendung

Das Token wird im HTTP-Header Authorization: Bearer <token> übergeben, oder (für die Produktion weniger empfohlen) in der URL über ?auth=<token>.

Bewährte Praktiken

• Ein Schlüssel pro Integration — erleichtert den unabhängigen Widerruf.
• Minimaler Geltungsbereich — aktivieren Sie nur die benötigten APIs, nicht standardmäßig alle.
• Ablauf auf der richtigen Ebene — nutzen Sie den Ablauf des Schlüssels, um eine dauerhafte Integration zu steuern; nutzen Sie den Ablauf des Tokens für einen temporären, nicht änderbaren Zugriff.
• Regelmäßige Rotation — generieren Sie den Schlüssel alle 6-12 Monate neu.
• Nicht in Git — das Token darf nicht in einem öffentlichen Repository versioniert werden. Verwenden Sie die Umgebungsvariablen Ihres Servers.

Unterschied zu OIDC / SSO

Um echte Benutzer mit ihrer institutionellen Identität anzumelden, verwenden Sie OIDC / SSO. Das API-Token ist für technische Server-zu-Server-Integrationen bestimmt, nicht für die tägliche Anmeldung der Benutzer.