Tutorial
API-Token erstellen und die erste Abfrage schicken
Ein Token mit den kleinstmöglichen Rechten anlegen, die erste Abfrage mit curl schicken, Rate-Limit-Header lesen und Token sauber rotieren.
Zuletzt aktualisiert:
Alles, was das Board kann, kann auch ein Skript: Karten anlegen, Zeiten buchen, Releases veröffentlichen, Build-Status melden. Diese Anleitung führt vom leeren Terminal zur ersten erfolgreichen Antwort. Der API-Zugriff gehört zum Developer-Plan.
Was du brauchst
- Den Developer-Plan — siehe Preise.
curloder ein beliebiges HTTP-Werkzeug.
1. Plan prüfen
Der API-Zugriff wird bei jeder Anfrage geprüft. Ohne Developer-Plan antwortet /api/v1 nicht — unabhängig davon, wie gültig das Token aussieht.
2. Developer-Konsole öffnen
In Zuuna gibt es einen eigenen Bereich für Tokens, Webhooks und die Endpunkt-Referenz. Dort entsteht auch das Token.
3. Token mit den kleinstmöglichen Scopes erstellen
Wähle nur, was das Skript wirklich tut. Ein CI-Runner, der Build-Status meldet, braucht git:write — und sonst nichts.
| Scope | Erlaubt |
|---|---|
boards:read | Boards und Spalten lesen |
cards:read / cards:write | Karten lesen / anlegen und ändern |
comments:read / comments:write | Kommentare lesen / schreiben |
time:read / time:write | Zeiten lesen / buchen |
git:write | Commits, Branches, Merges und Build-Status melden |
releases:write | Releases anlegen und veröffentlichen |
deployments:write | Deploy-Fortschritt melden |
webhooks:manage | Webhooks verwalten und das Zustell-Protokoll lesen |
Lesen und Schreiben sind bei Kommentaren und Zeiten mit Absicht getrennt: Kommentare enthalten den freiesten Text auf einer Karte, und gebuchte Zeit ist letztlich eine Stundenaufstellung. Ein Bot, der schreibt, muss deshalb nicht auch alles mitlesen dürfen.
Das Token wird genau einmal angezeigt. Kopier es sofort in deinen Passwortspeicher oder in das Secret deiner Pipeline — danach siehst du nur noch sein Präfix.
4. Erste Abfrage schicken
curl -sS https://app.zuuna.de/api/v1/boards \
-H "Authorization: Bearer $ZUUNA_TOKEN"Gib das Token über eine Umgebungsvariable weiter, nicht direkt in der Kommandozeile — die Shell-Historie merkt sich jedes Argument im Klartext.
5. Rate-Limit-Header lesen
Jede Antwort trägt Header, aus denen dein verbleibendes Kontingent hervorgeht. Im Developer-Plan sind es 3.000 Anfragen pro Minute. Wer über das Limit geht, bekommt 429 — ein kurzes Warten und ein erneuter Versuch reichen dann.
6. Token widerrufen und rotieren
Tokens laufen nicht von selbst ab. Widerrufe daher konsequent, was du nicht mehr brauchst, und rotiere die aktiven regelmäßig: neues Token erstellen, Skript umstellen, altes widerrufen. Für jedes System ein eigenes Token — dann kostet ein einzelner Widerruf nicht gleich alle Integrationen.
Wenn es nicht klappt
- 401. Kein oder falscher Bearer-Header, oder das Token wurde widerrufen.
- 403 mit einem Hinweis auf eine fehlende Berechtigung. Entweder fehlt dem Token der passende Scope, oder der Workspace hat keinen Developer-Plan.
- 429. Rate-Limit erreicht. Kurz warten und wiederholen; bei Massenoperationen Aufrufe bündeln.
- Leere Liste, obwohl es Boards gibt. Das Token gehört zu einem anderen Workspace als erwartet.
Nächste Schritte
- Build- und Test-Status auf der Karte anzeigen — die erste sinnvolle Anwendung.
- Commits automatisch mit Karten verknüpfen.
- Projektmanagement für Entwickler.
Häufige Fragen
Welche Scopes gibt es?
boards:read, cards:read, cards:write, comments:read, comments:write, time:read, time:write, git:write, releases:write, deployments:write und webhooks:manage. Lesen und Schreiben sind bei Kommentaren und Zeiten bewusst getrennt: Ein CI-Bot, der einen Kommentar schreibt, soll nicht die ganze Diskussion mitlesen dürfen.
Wie hoch ist das Rate-Limit?
3.000 Anfragen pro Minute im Developer-Plan. Die individuelle Ausbaustufe hebt die Grenze auf. Niedrigere Pläne enthalten keinen API-Zugriff, deshalb stellt sich die Frage dort nicht.
Kann ich ein Ablaufdatum setzen?
Ein Ablaufdatum lässt sich in der Oberfläche heute nicht setzen. Rotiere Tokens stattdessen von Hand: neues erstellen, umstellen, altes widerrufen.
Sieht die API private Boards?
Sie sieht genau das, was der Workspace des Tokens sieht, eingeschränkt durch die gewählten Scopes. Ein Token reicht nie weiter als der Workspace, in dem es erstellt wurde.
Wo finde ich die vollständige Referenz?
In der Developer-Dokumentation in der App unter /developers — dort stehen alle Endpunkte, Scopes und Webhook-Ereignisse.