Omniscol-API — Authentifizierungstoken

Schlüssel und Token: zwei verschiedene Objekte

Omniscol unterscheidet zwei Objekte, die nicht verwechselt werden dürfen.

Ein Schlüssel ist ein dauerhaftes Objekt, das auf Omniscol-Seite aufbewahrt wird. Er vereint:

• eine kurze, zufällig generierte, öffentliche Kennung: Sie ist es, die die Liste anzeigt, und sie reist in jedem Token mit, um den zu prüfenden Schlüssel zu bezeichnen;
• eine beschreibende Bezeichnung, jederzeit änderbar;
• ein optionales Ablaufdatum, jederzeit änderbar;
• ein langes, serverseitig gezogenes zufälliges Geheimnis, das als kryptografischer Signaturschlüssel dient.

Die Kennung, die Bezeichnung und das Ablaufdatum sind Verwaltungsinformationen: Die Kennung ist nur eine öffentliche Referenz, kein geheimes Element. Das Geheimnis hingegen ist das einzige Signaturmaterial: bei der Erstellung des Schlüssels zufällig generiert, bleibt es auf Serverseite, ist nicht änderbar und wird niemals angezeigt oder zurückgegeben — weder bei der Erstellung noch in der Schlüsselliste. Und selbst wenn es durchsickerte, würde es nicht ausreichen, um ein Token zu fälschen: Die Signatur kombiniert es mit einem kontospezifischen Salz und einem Servergeheimnis, die ihrerseits ebenfalls niemals Omniscol verlassen.

Ein Token ist ein eigenständiges JWT (JSON Web Token), das mit dem Geheimnis des Schlüssels signiert ist. Es ist das, was Sie an das externe System übergeben. Sein signierter Inhalt trägt das betroffene Konto, die Liste der zugelassenen Endpunkte, den Schlüssel, von dem es abgeleitet ist, und sein eigenes Ablaufdatum.

Mit anderen Worten: Ein Schlüssel signiert, ein Token wird signiert. Derselbe Schlüssel kann mehrere Token signieren — alle mit demselben Geheimnis prüfbar, also alle gemeinsam widerrufen, wenn der Schlüssel verschwindet.

Omniscol speichert das Token nicht: Es generiert es, zeigt es einmal an und prüft es dann bei jedem Aufruf erneut, indem es seine Signatur aus dem Geheimnis des Schlüssels rekonstruiert (HMAC SHA-256). Keine vom Token getragene Berechtigung kann somit ohne dieses Geheimnis verändert werden.

Ein Token erstellen

Der Bildschirm Teilen steht in Verwaltung → Import/Export auf Premium-Konten zur Verfügung. Die Erstellung erfolgt in zwei Schritten: Man erstellt zuerst einen Schlüssel und generiert dann ein Token aus diesem Schlüssel.

1. Einen Schlüssel erstellen — geben Sie eine aussagekräftige Bezeichnung und, wenn der Zugriff temporär ist, ein Ablaufdatum an. Seine Bezeichnung und sein Ablauf bleiben nachträglich änderbar; sein Signaturgeheimnis nicht.
2. Ein Token generieren — wählen Sie den Schlüssel, kreuzen Sie die zugelassenen Endpunkte an, wählen Sie gegebenenfalls ein token-eigenes Ablaufdatum und generieren Sie dann das JWT.

Bei der Generierung zeigt Omniscol das Token nur ein einziges Mal an. Kopieren Sie es sofort in einen Passwort-Manager: Es wird nicht erneut angezeigt. Der Ablauf des Tokens ist in seinen signierten Inhalt eingetragen: Er lässt sich nicht nachträglich ändern. Um dieses Datum zu ändern, generieren Sie ein neues Token.

Es gibt also zwei Ablaufebenen, die voneinander unabhängig sind:

• Ablauf des Schlüssels — über die Schlüsselliste änderbar; wenn er erreicht ist, werden alle von diesem Schlüssel abgeleiteten Token abgelehnt (der Aufruf scheitert mit einem 401);
• Ablauf des Tokens — bei der Generierung festgelegt, in das JWT eingetragen und danach nicht mehr änderbar.

Zugelassene Endpunkte

Ein Token gewährt Zugriff nur auf die bei seiner Generierung angekreuzten Endpunkte: Gehen Sie niemals davon aus, dass es die gesamte API abdeckt. Die zugelassene Liste wird im Token transportiert und bei jedem Aufruf geprüft; ein Aufruf an einen nicht zugelassenen Endpunkt wird abgelehnt (401).

Über die einzelnen Endpunkte hinaus bietet die Auswahlliste Modul-Abkürzungen:

• der Eintrag eines Moduls allein lässt alle seine Endpunkte zu;
• die Varianten pro Vorgang — Lesen, Ändern, Erstellen, Löschen — beschränken das Modul auf einen einzigen Aufruftyp.

Das Ankreuzen von „Stundenpläne [Lesen]“ gewährt somit den gesamten Lesezugriff auf die Stundenpläne, ohne den geringsten Schreibzugriff zu öffnen und ohne jeden Endpunkt einzeln anzukreuzen. Bleiben Sie so knapp wie möglich: Gewähren Sie nur die Module und die Vorgänge, die für die Integration unbedingt erforderlich sind.

Ein Token verwenden

Zwei übliche Arten, das Token an die API zu senden:

• HTTP-Header: Authorization: Bearer <token> (empfohlen).
• Query-String: ?auth=<token> (praktisch zum Debuggen, erscheint aber in den HTTP-Logs — in der Produktion zu vermeiden).

curl-Beispiel, mit einem echten Endpunkt aus der OpenAPI anzupassen:

curl -H "Authorization: Bearer $TOKEN" \
  https://ihre-schule.omniscol.com/api/<module>/<endpunkt>

OpenAPI-Dokumentation

Der Bildschirm Import/Export zeigt einen Link OpenAPI 3.1 an, der die für das Konto verfügbare Spezifikation im Swagger Editor öffnet. Dort finden Sie:

• die Liste der bereitgestellten API-Endpunkte,
• die Schemata der ausgetauschten Daten,
• die Methoden und Parameter,
• die erwarteten Antworten.

Die Spezifikation wird auch direkt von Ihrem Konto bereitgestellt, ohne Authentifizierung:

• /api/guest/openapi.json — Spezifikation im JSON-Format;
• /api/guest/openapi.yaml (oder /api/guest/openapi?yaml=true) — derselbe Inhalt im YAML-Format;
• /api/guest/school_schema.json — JSON-Schema der Daten des Kontos.

Das vollständige Handbuch für Ihren KI-Assistenten

Das Portal veröffentlicht die gesamte Omniscol-Hilfe auch als einzelne Textdatei, bereit als Wissensbasis für einen KI-Assistenten (Claude-Projekt, individuelles GPT…):

• omniscol.com/de/llms-full.txt — das vollständige Handbuch in Markdown, verfügbar in jeder Sprache der Hilfe (/en/llms-full.txt, /fr/llms-full.txt…);
• omniscol.com/llms.txt — der Index im Standard llms.txt, den KI-Suchmaschinen automatisch finden.

Einen Zugriff widerrufen

Der Widerruf erfolgt auf der Ebene des Schlüssels, nicht des einzelnen Tokens.

Der Bildschirm listet die Schlüssel auf, die zur Generierung von Token gedient haben. Einen Schlüssel zu löschen entfernt sein Signaturgeheimnis auf Omniscol-Seite: Von da an kann keine von diesem Geheimnis abgeleitete Signatur mehr geprüft werden, und jeder Aufruf, der ein aus diesem Schlüssel stammendes Token vorlegt, scheitert mit einem 401. Es ist das Fehlen des Geheimnisses, das die Token ungültig macht, nicht eine Widerrufsliste.

Für die IT-Abteilung zwei Konsequenzen:

• Es gibt keinen Widerruf Token für Token. Omniscol bewahrt die ausgestellten JWT nicht auf und kann keines einzeln deaktivieren: Ein bereits generiertes Token bleibt bis zu seinem eigenen Ablauf gültig oder bis sein Schlüssel gelöscht oder abgelaufen ist.
• Den Ablauf eines Schlüssels zu ändern wirkt sich sofort auf alle seine Token aus: Dieses Datum vorzuverlegen kappt den Zugriff sämtlicher aus dem Schlüssel stammenden Token.

Bewährte Vorgehensweise: Löschen Sie unverzüglich jeden Schlüssel, dessen Durchsickern Sie vermuten, und erstellen Sie dann einen Ersatzschlüssel mit einer aussagekräftigen Bezeichnung.

Ein Schlüssel pro Ziel und pro Verwendung

Da der Widerruf pro Schlüssel erfolgt, widmen Sie jeder Integration einen Schlüssel (eine externe Software = ein Schlüssel). Das Geheimnis eines Schlüssels signiert nur seine eigenen Token: Diesen Schlüssel zu löschen macht nur die Zugriffe der betroffenen Integration ungültig, ohne die anderen zu berühren.

Umgekehrt macht ein einziger, zwischen mehreren Systemen geteilter Schlüssel jeden Widerruf brutal: Den kompromittierten Schlüssel zu löschen kappt auf einen Schlag alle Systeme, die ihn nutzten.

Für welche Integrationen

Die API wird typischerweise verwendet für:

• maßgeschneiderte Signage-Systeme (über die nativen Omniscol-Anzeigetafeln hinaus; siehe Anpassung der Anzeigetafeln),
• externe Dashboards, die Omniscol und andere Quellen konsolidieren,
• Konnektoren oder Synchronisierungen mit einem ERP oder einem fachlichen Informationssystem,
• MCP-kompatible KI-Agenten, die Omniscol über den MCP-Server abfragen; siehe MCP — einen externen KI-Agenten verbinden.

Für einen delegierten Zugriff durch einen identifizierten Drittdienst (gescoptes Token, Zustimmung des Benutzers, widerrufbar durch Deaktivieren des Clients) bevorzugen Sie den OAuth2-Server von Omniscol: siehe OAuth2 / OIDC (Anbieter).