Tutorial
Create an API token and make your first call
Create a token with the smallest possible rights, make your first call with curl, read the rate-limit headers and rotate tokens cleanly.
Last updated:
Anything the board can do, a script can do too: create cards, log time, publish releases, report build status. This guide goes from an empty terminal to your first successful response. API access belongs to the Developer plan.
What you need
- The Developer plan — see pricing.
curlor any HTTP client.
1. Check your plan
API access is checked on every request. Without the Developer plan /api/v1 does not answer, however valid the token looks.
2. Open the developer console
Zuuna has its own area for tokens, webhooks and the endpoint reference. The token is created there.
3. Create a token with the smallest possible scopes
Pick only what the script actually does. A CI runner reporting build status needs git:write — and nothing else.
| Scope | Allows |
|---|---|
boards:read | read boards and columns |
cards:read / cards:write | read / create and change cards |
comments:read / comments:write | read / post comments |
time:read / time:write | read / log time |
git:write | report commits, branches, merges and build status |
releases:write | create and publish releases |
deployments:write | report deployment progress |
webhooks:manage | manage webhooks and read the delivery log |
Read and write are deliberately separate for comments and time: comments carry the most free-form text on a card, and logged time is ultimately a timesheet. A bot that writes need not also be able to read everything back out.
The token is shown exactly once. Copy it straight into your password manager or your pipeline secret — afterwards only its prefix is visible.
4. Make your first call
curl -sS https://app.zuuna.de/api/v1/boards \
-H "Authorization: Bearer $ZUUNA_TOKEN"Pass the token through an environment variable rather than directly on the command line — shell history keeps every argument verbatim.
5. Read the rate-limit headers
Every response carries headers showing how much of your allowance remains. On the Developer plan that is 3,000 requests per minute. Going over returns 429; a short wait and a retry is all it takes.
6. Revoke and rotate tokens
Tokens do not expire on their own. So revoke what you no longer need, and rotate the active ones regularly: create a new token, switch the script over, revoke the old one. One token per system — then a single revocation does not take down every integration at once.
Troubleshooting
- 401. Missing or wrong bearer header, or the token was revoked.
- 403 mentioning a missing capability. Either the token lacks the right scope, or the workspace is not on the Developer plan.
- 429. Rate limit reached. Wait briefly and retry; batch your calls for bulk operations.
- An empty list although boards exist. The token belongs to a different workspace than you expected.
Next steps
- Show build status on the card — the first useful application.
- Link commits to cards automatically.
- Project management for developers.
FAQ
Which scopes are there?
boards:read, cards:read, cards:write, comments:read, comments:write, time:read, time:write, git:write, releases:write, deployments:write and webhooks:manage. Read and write are deliberately separate for comments and time: a CI bot posting a comment should not thereby be able to read the whole discussion.
What is the rate limit?
3,000 requests per minute on the Developer plan. The custom tier lifts the limit entirely. Lower plans include no API access, so the question does not arise there.
Can I set an expiry date?
An expiry cannot be set in the interface today. Rotate tokens by hand instead: create a new one, switch over, revoke the old one.
Does the API see private boards?
It sees exactly what the token's workspace sees, narrowed by the scopes you chose. A token never reaches beyond the workspace it was created in.
Where is the full reference?
In the developer documentation inside the app at /developers — every endpoint, scope and webhook event is listed there.