API-Token

• Was ist ein API-Token?
• Voraussetzungen
• Wo finde ich die API-Token?
• Ein Token erstellen
• Das Token wird nur einmal angezeigt
• Was die Token-Liste zeigt
• Ein Token widerrufen
• Das Token verwenden

Was ist ein API-Token?

Mit der Klubraum REST API können eure eigenen Skripte, eure Vereinswebseite oder andere Werkzeuge mit den Kalender-Events und den Mitgliedern eures Vereins arbeiten. Jede Anfrage weist sich dabei mit einem Personal Access Token aus, das du in der Klubraum App erstellst.

So ein Token gehört immer zu genau einem Klubraum und zu der Person, die es erstellt hat. Es hat nur die Scopes, die du ihm gibst, es kann ablaufen, und du kannst es jederzeit widerrufen. Vor allem aber kann ein Token nie mehr als du selbst: Bei jeder Anfrage werden zusätzlich deine aktuellen Rechte in der App geprüft. Verlierst du ein Recht, verliert das Token es ebenfalls.

Voraussetzungen

• Du bist Administrator des Klubraums. Andere Mitglieder sehen diese Funktion nicht.
• Euer Verein hat einen passenden Tarif: Mitgliederliste, Einladungen und Entfernen von Mitgliedern sind in Plus enthalten, jeder andere Endpunkt braucht Pro. Ohne passenden Tarif erscheint beim Tippen auf die Kachel ein Hinweis zum Upgrade.

Wo finde ich die API-Token?

Öffne die Einstellungen und dort Aktueller Klubraum. Die zweite Kachel heißt API-Token, mit dem Untertitel Personal Access Tokens für die Klubraum API – direkt unter der Kachel zum Ändern des Vereinsnamens.

Achtung: Die Kachel direkt darunter gehört zum Token für Beitrittsanfragen. Das ist ein anderes Token, das nur für das Beitrittsformular auf eurer Vereinswebseite gedacht ist – mehr dazu unter Beitrittsanfrage auf Vereinswebseite.

Ein Token erstellen

Tippe oben rechts auf das + (Token erstellen). Der Dialog API-Token erstellen fragt dich nach drei Dingen.

Name

Freier Text mit maximal 100 Zeichen, zum Beispiel “Website-Sync”. Gib jedem Werkzeug ein eigenes Token und benenne es nach diesem Werkzeug – dann weißt du später genau, welches Token du widerrufen darfst.

Scopes

Hier legst du fest, was das Token darf. Es gibt vier Scopes:

• members:read – die Mitgliederliste lesen.
• members:write – Mitglieder einladen und entfernen.
• events:read – Kalender-Events lesen.
• events:write – Kalender-Events erstellen, ändern, absagen und löschen.

Ein Schreib-Scope schließt den passenden Lese-Scope immer mit ein. Sobald du members:write ankreuzt, wird members:read automatisch mit angekreuzt und lässt sich nicht mehr abwählen; gespeichert wird dann nur der Schreib-Scope. Dasselbe gilt für events:write und events:read. Mindestens ein Scope ist erforderlich.

Tipp: Wähle so wenige Scopes wie möglich. Ein Skript, das eure Events nur auf eurer Webseite anzeigt, braucht events:read und sonst nichts.

Läuft ab nach

Wähle 30, 90, 180 oder 365 Tage – oder Nie. Bei Nie erscheint eine Warnung, und das zu Recht: Ein Token ohne Ablaufdatum bleibt gültig, bis es jemand widerruft. Gib einem Token deshalb möglichst eine begrenzte Lebensdauer.

Tippe anschließend auf Erstellen.

Das Token wird nur einmal angezeigt

Direkt nach dem Erstellen zeigt dir die App das vollständige Token – die lange geheime Zeichenkette, die mit klubraum_pat_ beginnt. Kopiere sie über die Kopier-Schaltfläche und hinterlege sie sofort dort, wo dein Skript oder Werkzeug sie liest, am besten in einem Passwort-Manager oder einem Secrets-Speicher.

Wichtig: Das ist der einzige Moment, in dem die geheime Zeichenkette sichtbar ist. Sie lässt sich später nicht mehr abrufen, auch nicht von uns. Wenn du sie verlierst, widerrufe das Token und erstelle ein neues.

Gib die geheime Zeichenkette niemals an einen öffentlichen Ort: nicht in das JavaScript eurer Webseite, nicht in ein öffentliches Repository und nicht in eine Vereins-Konversation. Wer sie hat, kann die API genau mit den Scopes nutzen, die du dem Token gegeben hast.

Was die Token-Liste zeigt

Auf dem Bildschirm siehst du alle Token eures Klubraums. Zu jedem Token findest du:

• den Namen, den du vergeben hast,
• ein kurzes Präfix, das mit klubraum_pat_ beginnt und das Token benennt, ohne die geheime Zeichenkette zu verraten,
• die Scopes als Chips,
• wann es erstellt wurde, wann es abläuft und wann es zuletzt benutzt wurde.

Am Datum der letzten Nutzung erkennst du gut, welche Token niemand mehr braucht. Widerrufene Token bleiben in der Liste stehen und werden durchgestrichen dargestellt.

Ein Token widerrufen

Tippe beim jeweiligen Token auf das Lösch-Symbol (Token widerrufen) und bestätige mit Ja, widerrufen. Der Widerruf gilt sofort: Ab diesem Moment wird jede Anfrage mit diesem Token abgelehnt. Rückgängig machen lässt sich das nicht – ein widerrufenes Token kann nicht wieder aktiviert werden.

Tipp: Du möchtest ein Token austauschen, das noch im Einsatz ist? Dann erstelle zuerst das neue Token, stelle dein Skript oder Werkzeug darauf um und widerrufe erst danach das alte.

Das Token verwenden

Schicke das Token bei jeder Anfrage als Bearer-Token im Authorization-Header mit:

Authorization: Bearer klubraum_pat_…

Welche Endpunkte es gibt, welche Parameter sie erwarten und was sie zurückgeben, steht im Entwicklerbereich und in der interaktiven API-Referenz. Auf Englisch.