API Omniscol — tokeny uwierzytelniające

Klucz i token: dwa odrębne obiekty

Omniscol rozróżnia dwa obiekty, których nie wolno ze sobą mylić.

Klucz to obiekt trwały, przechowywany po stronie Omniscol. Łączy w sobie:

• krótki identyfikator, generowany losowo, publiczny: to on pojawia się na liście i jest przenoszony w każdym tokenie, aby wskazać klucz do weryfikacji;
• opisową etykietę, modyfikowalną w każdej chwili;
• opcjonalną datę wygaśnięcia, również modyfikowalną w każdej chwili;
• długi losowy sekret, wylosowany po stronie serwera, który służy jako kryptograficzny klucz podpisu.

Identyfikator, etykieta i data wygaśnięcia to informacje administracyjne: identyfikator jest tylko publicznym odnośnikiem, a nie elementem tajnym. Natomiast sekret jest jedynym materiałem podpisu: wygenerowany losowo przy tworzeniu klucza, zostaje po stronie serwera, nie podlega zmianie i nigdy nie jest wyświetlany ani zwracany — ani przy tworzeniu, ani na liście kluczy. A nawet gdyby wyciekł, nie wystarczyłby do podrobienia tokenu: podpis łączy go z solą właściwą dla konta oraz sekretem serwera, które również nigdy nie opuszczają Omniscol.

Token to samodzielny JWT (JSON Web Token), podpisany sekretem klucza. To właśnie on jest przekazywany systemowi zewnętrznemu. Jego podpisana treść zawiera konto, którego dotyczy, listę dozwolonych punktów dostępu, klucz, z którego pochodzi, oraz własną datę wygaśnięcia.

Innymi słowy: klucz podpisuje, token jest podpisany. Ten sam klucz może podpisać wiele tokenów — wszystkie weryfikowalne tym samym sekretem, a więc wszystkie unieważnione razem, gdy klucz zniknie.

Omniscol nie przechowuje tokenu: generuje go, wyświetla raz, a potem weryfikuje przy każdym wywołaniu, odtwarzając jego podpis z sekretu klucza (HMAC SHA-256). Żadne uprawnienie przenoszone przez token nie może więc zostać zmienione bez tego sekretu.

Tworzenie tokenu

Ekran Udostępnianie jest dostępny w module Administracja → Import/Eksport na kontach Premium. Tworzenie przebiega w dwóch etapach: najpierw tworzy się klucz, a następnie generuje token z tego klucza.

1. Utworzenie klucza — proszę podać opisową etykietę oraz, jeśli dostęp jest tymczasowy, datę wygaśnięcia. Jego etykietę i datę wygaśnięcia można zmienić później; jego sekretu podpisu — nie.
2. Wygenerowanie tokenu — proszę wybrać klucz, zaznaczyć dozwolone punkty dostępu, ewentualnie wybrać datę wygaśnięcia właściwą dla tokenu, a następnie wygenerować JWT.

Przy generowaniu Omniscol wyświetla token tylko raz. Proszę natychmiast skopiować go do menedżera sekretów: nie zostanie już wyświetlony ponownie. Data wygaśnięcia tokenu jest wpisana w jego podpisaną treść: nie zmienia się jej po fakcie. Aby zmienić tę datę, proszę wygenerować nowy token.

Istnieją więc dwa poziomy wygaśnięcia, niezależne od siebie:

• wygaśnięcie klucza — można je zmienić z listy kluczy; po jego nadejściu wszystkie tokeny pochodzące z tego klucza są odrzucane (wywołanie kończy się błędem 401);
• wygaśnięcie tokenu — ustalone przy generowaniu, wpisane w JWT i później już niezmienne.

Dozwolone punkty dostępu

Token daje dostęp wyłącznie do punktów dostępu zaznaczonych przy jego generowaniu: nigdy nie należy zakładać, że obejmuje całe API. Dozwolona lista jest przenoszona w tokenie i weryfikowana przy każdym wywołaniu; wywołanie niedozwolonego punktu dostępu zostaje odrzucone (401).

Poza pojedynczymi punktami dostępu lista wyboru proponuje skróty na poziomie modułu:

• wpis samego modułu dopuszcza wszystkie jego punkty dostępu;
• warianty według operacji — odczyt, modyfikacja, tworzenie, usuwanie — zawężają moduł do jednego rodzaju wywołań.

Zaznaczenie „Plany lekcji [odczyt]” daje więc pełny odczyt tego modułu, nie otwierając żadnego zapisu i bez zaznaczania każdego punktu dostępu po kolei. Proszę trzymać się minimum: przyznawać tylko te moduły i operacje, które są bezwzględnie konieczne dla integracji.

Używanie tokenu

Dwa zwyczajowe sposoby przesłania tokenu do API:

• Nagłówek HTTP: Authorization: Bearer <token> (zalecany).
• Parametr adresu URL: ?auth=<token> (wygodny przy debugowaniu, ale pojawia się w logach HTTP — należy go unikać w środowisku produkcyjnym).

Przykład curl, do dostosowania z rzeczywistym punktem dostępu wziętym z OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://nazwa-szkoly.omniscol.com/api/<modul>/<punkt-dostepu>

Dokumentacja OpenAPI

Ekran Import/Eksport pokazuje link OpenAPI 3.1, który otwiera specyfikację dostępną dla konta w Swagger Editor. Znajdują się w niej:

• lista udostępnionych punktów dostępu API,
• schematy wymienianych danych,
• metody i parametry,
• oczekiwane odpowiedzi.

Specyfikacja jest też udostępniana bezpośrednio przez konto, bez uwierzytelniania:

• /api/guest/openapi.json — specyfikacja w formacie JSON;
• /api/guest/openapi.yaml (albo /api/guest/openapi?yaml=true) — ta sama treść w formacie YAML;
• /api/guest/school_schema.json — schemat JSON danych konta.

Pełna pomoc dla asystenta AI

Portal publikuje też całą pomoc Omniscol w jednym pliku tekstowym, gotowym do wykorzystania jako baza wiedzy asystenta AI (projekt Claude, własny GPT…):

• omniscol.com/pl/llms-full.txt — pełny przewodnik w formacie Markdown, dostępny w każdym języku pomocy (/en/llms-full.txt, /de/llms-full.txt…);
• omniscol.com/llms.txt — indeks w standardzie llms.txt, który silniki AI odnajdują automatycznie.

Unieważnianie dostępu

Unieważnienie odbywa się na poziomie klucza, a nie pojedynczego tokenu.

Ekran wymienia klucze, które posłużyły do wygenerowania tokenów. Usunięcie klucza wymazuje jego sekret podpisu po stronie Omniscol: od tej chwili żaden podpis pochodzący z tego sekretu nie może już zostać zweryfikowany, a każde wywołanie z tokenem wydanym z tego klucza kończy się błędem 401. To brak sekretu unieważnia tokeny, a nie lista unieważnień.

Dla działu IT dwie konsekwencje:

• Nie ma unieważniania token po tokenie. Omniscol nie przechowuje wydanych JWT i nie może wyłączyć jednego z nich osobno: raz wygenerowany token pozostaje ważny do własnego wygaśnięcia albo do chwili, gdy jego klucz zostanie usunięty lub wygaśnie.
• Zmiana daty wygaśnięcia klucza działa natychmiast na wszystkie jego tokeny: przesunięcie tej daty wcześniej odcina dostęp wszystkim tokenom wydanym z tego klucza.

Dobra praktyka: klucz, co do którego istnieje podejrzenie wycieku, należy usunąć bezzwłocznie, a potem utworzyć klucz zastępczy z opisową etykietą.

Jeden klucz na cel i na zastosowanie

Skoro unieważnianie odbywa się na poziomie klucza, każdej integracji należy dedykować osobny klucz (jedno oprogramowanie zewnętrzne = jeden klucz). Sekret klucza podpisuje tylko jego własne tokeny: usunięcie tego klucza unieważnia wyłącznie dostępy danej integracji, nie naruszając pozostałych.

Odwrotnie, jeden klucz dzielony między kilka systemów sprawia, że każde unieważnienie działa na zasadzie wszystko albo nic: usunięcie klucza, który wyciekł, odcina od razu wszystkie systemy, które się nim posługiwały.

Do jakich integracji

API jest zwykle używane do:

• własnych systemów ekranów informacyjnych (wykraczających poza wbudowane panele informacyjne Omniscol; zob. Personalizacja paneli),
• zewnętrznych paneli zarządczych konsolidujących Omniscol i inne źródła,
• konektorów lub synchronizacji z systemem ERP albo dziedzinowym systemem informatycznym,
• agentów AI zgodnych z MCP korzystających z Omniscol przez serwer MCP; zob. MCP — podłączenie zewnętrznego agenta AI.

W przypadku dostępu delegowanego zidentyfikowanej usłudze zewnętrznej (token o zawężonym zakresie, zgoda użytkownika, możliwość unieważnienia przez wyłączenie klienta) lepszy jest serwer OAuth2 Omniscol: zob. OAuth2 / OIDC (dostawca).