einfache Schule

Bevor Ihre App beginnen kann Anfragen zu stellen, müssen Sie sich authentifizieren. Dafür verwenden wir den OAuth Standard. Hier haben Sie zwei verschiedene Möglichkeiten.

OAuth-Client

Wie man sich mit einem OAuth Client anmeldet wird zum Beispiel hier erklärt. Viele Programmiersprachen und Frameworks bieten hier Libraries an, welche den Authentifizierungsflow übernehmen.

Um so einen OAuth-Client zu erstellen, meldet man sich bei beste.schule an und navigiert auf das eigene Benutzerkonto (oben rechts auf den Namen klicken und dann auf "Benutzerkonto"). Wenn man dann links auf den Reiter "API" klickt, kann man sich ganz unten unter "OAuth-Clients" einen solchen Client erstellen. Dort erhält man dann die Client-ID, gegebenenfalls das Client-Secret und man setzt die Callback-URL, also die URL Ihrer App, die für die OAuth-Authentifizierung zuständig ist.

Wir halten uns bei den OAuth-Routen an den OAuth-Standard:

Route	Beschreibung
`https://beste.schule/oauth/authorize`	Authorization Endpoint
`https://beste.schule/oauth/join`	Ebenfalls der Authorization Endpoint, aber für Nutzer, die sich noch nicht registriert haben
`https://beste.schule/oauth/token`	Token Endpoint, welcher auf einem Authorization Code einen Access Token macht

Personal Access Token

Mit so einem Token kann man sofort die API ansprechen und bekommt Antworten, wie als wäre man mit dem eigenen beste.schule Benutzeraccount angemeldet.

Dieser Token ist wie Ihr Passwort. Jede Person, die Zugriff darauf hat, kann im Namen des Benutzeraccounts handeln, ohne dass das Passwort gebraucht wird.

So ein Token lässt sich erstellen, indem Sie sich in beste.schule anmeldeen und auf das eigene Benutzerkonto navigiert (oben rechts auf den Namen klicken und dann auf "Benutzerkonto"). Wenn man dann links auf den Reiter "API" klickt, kann man sich ganz unten unter "Personal Access Token" so einen Token erstellen.

Authentifizierung

Nun sollten Sie in jedem Fall einen Access Token haben. Um sich mit der API zu authentifizieren, müssen Sie bei Ihrer Anfrage den Header Authorization hinzufügen mit dem Wert Bearer <Access Token>, wobei <Access Token> Ihr Access Token ist.