Das MTK-Portal stellt eine Leistungsstarke REST-API zu Verfügung. Die API unterstützt alle Funtionen die auch die das Fronted ermöglicht dadurch besteht eine Feature Parity.
Die aktuelle Version der API ist:
v1
Alle Endpunkte sind versionsbasiert aufgebaut und folgen diesem Schema:
https://api.portal.schulen-mtk.org/api/<version>/<path>
Für die aktuelle Version lautet die Basis-URL somit:
https://api.portal.schulen-mtk.org/api/v1/<path>
GET https://api.portal.schulen-mtk.org/api/v1/users
Authorization: Bearer <ACCESS_TOKEN>
Aufgrund der aktuellen beta Phase kann es zu erweiterungen von bestehenden Endpunkten kommen.
Zur Authentifizierung muss im Authorization-Header ein gültiger Bearer Token übermittelt werden.
Dieser Token kann mit den persönlichen Zugangsdaten über unseren Identity Provider (Keycloak) angefordert werden.
POST https://auth.schulen-mtk.org/realms/schulen-mtk/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=password
client_id=openapi-mtkportal
username=<DeinNutzername>
password=<DeinPasswort>
otp=<DeinAktuellerOtpCode>
⚠️ Falls Multi-Faktor-Authentifizierung aktiviert ist, muss der aktuelle OTP-Code mitgesendet werden.
{
"access_token": "<ACCESS_TOKEN>",
"expires_in": 300,
"refresh_expires_in": 7200,
"refresh_token": "<REFRESH_TOKEN>",
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "<SESSION_STATE>",
"scope": "email profile"
}
Der Access Token ist 5 Minuten gültig und muss bei jedem API-Request im Header übermittelt werden:
Authorization: Bearer <ACCESS_TOKEN>
Der Token darf nicht in Anführungszeichen gesetzt werden.
Solange der Refresh Token gültig ist (2 Stunden), kann damit ein neuer Access Token angefordert werden.
POST https://auth.schulen-mtk.org/realms/schulen-mtk/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
client_id=openapi-mtkportal
refresh_token=<REFRESH_TOKEN>
{
"access_token": "<ACCESS_TOKEN>",
"expires_in": 300,
"refresh_expires_in": 7200,
"refresh_token": "<REFRESH_TOKEN>",
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "<SESSION_STATE>",
"scope": "email profile"
}
Nach Ablauf des Refresh Tokens ist eine erneute Authentifizierung erforderlich.
Die vollständige Endpoint-Dokumentation finden Sie unter:
🔗 https://api.portal.schulen-mtk.org/api/docs/
Die MTK-Portal API ist eine REST-basierte JSON-API.
application/jsonFür Requests müssen immer folgender Header gesetzt werden:
Content-Type: application/json
Beispiel:
POST /api/v1/example
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
{
"exampleField": "value"
}
Die API verwendet standardisierte HTTP-Statuscodes:
200 OK – Anfrage erfolgreich201 Created – Ressource erfolgreich erstellt204 No Content – Anfrage erfolgreich400 Bad Request – Ungültige Anfrage401 Unauthorized – Fehlende oder ungültige Authentifizierung403 Forbidden – Keine ausreichenden Berechtigungen404 Not Found – Ressource nicht gefunden500 Internal Server Error – Interner Serverfehler