Create a key
Owners and admins create keys under API in the account menu at the foot of the sidebar. Give the key a name that says what will hold it — Zendesk, CI · nightly — pick its role, and optionally the apps it may reach.
The key is shown once, when it is made. qarunbook keeps only a hash of it, so nobody — including us — can show it to you again. If it is lost, revoke it and make another.
qrk_live_Hq3v9sXa0LmP4tWc8yZr2NfB6jKd1uQe7oVh5gIx3TsSend it
Put the key in the Authorization header as a bearer token. Keep it in an environment variable, never in source — every example in these docs reads it from QARUNBOOK_KEY.
export QARUNBOOK_KEY="qrk_live_…"curl "https://qarunbook.com/api/v1/apps" \
-H "Authorization: Bearer $QARUNBOOK_KEY"Roles
A key has one of three roles, and they mean exactly what they mean for a teammate — the API checks them with the same rules the app does, app by app.
What each role can do
viewerread- Read apps, sections, checks, results and issues. Every write answers
403. For dashboards and status pages. testerread, test- Everything a viewer can, plus raise and reword issues and record results. For a support desk or a CI job.
adminread, test, fix- Everything a tester can, plus mark issues fixed and reopen them. For the tool that closes the loop when a fix ships.
There is no owner key. Billing, members and deleting a workspace belong to people, not to scripts. And nobody can make a key stronger than they are: an admin who was given only some apps can only make keys for those apps.
App scope
A key with no apps listed reaches every app in the workspace, including ones added later. List apps and it reaches only those. To a scoped key, every other app simply does not exist: it is missing from GET /apps, and naming it answers 404, not 403 — so a key cannot be used to learn what else is in the workspace.
Revoke and rotate
Revoking a key stops it on the very next request. Revoked keys stay on the list, greyed out, so there is a record of what had access and when it ended. To rotate, create the new key, deploy it, then revoke the old one — there is no moment where nothing works.
The list also shows when each key was last used, to the minute. A key nobody has used in months is a key to revoke.
Keeping keys safe
Server-side only
A key is a password for part of your workspace. Never put one in a mobile app, a browser bundle or a public repository — anything shipped to a device can be read off it. Call the API from your server, your CI runner or a serverless function, with the key in that environment's secrets.
Give each integration its own key, at the lowest role that does the job, scoped to the apps it touches. Then revoking one never breaks another, and a leak is contained to what that one key could do.
When it fails
401 — no key, or not a live one
A missing, mistyped or revoked key all answer the same way. Personal MCP tokens (qarb_…) are not API keys and are refused here too.
{
"error": {
"code": "unauthorized",
"message": "Missing, unknown or revoked API key. Send it as `Authorization: Bearer qrk_live_…`."
}
}402 — not on a paid plan
The key is real, but the workspace is on Free or Early access.
{
"error": {
"code": "plan_required",
"message": "The API is available on paid plans."
},
"upgrade": true
}403 — the key's role is too low
{
"error": {
"code": "forbidden",
"message": "This key is read-only. Writing needs a tester or admin key."
}
}