API tokens and scopes
An API token is a long-lived credential for your own systems: CI, cron,
curl, an AI agent. It never expires and is revoked explicitly, and it carries
only the scopes you tick when you create it. (Scopes beyond notifications:
since v0.4.1.)
Create one
Section titled “Create one”- In the Console, open Settings > API tokens (the same section also appears on the Notifications page) and click Create token.
- Name it after the system that will use it (
ci,backup-cron,claude-code). - Tick the scopes it needs.
- Copy the
dak_…secret: it is shown exactly once.
The scopes
Section titled “The scopes”| Scope | What it unlocks | Typical holder |
|---|---|---|
Read-only (read) |
list hosts, services, watchdogs, uptime and your account limits. No changes | a dashboard, a status script |
Manage hosts (hosts:manage) |
enroll new hosts (mint join tokens), remove hosts, run updates | a provisioning script, an AI agent |
Manage services (services:manage) |
publish and unpublish exports, public ports, gateway ports, proxy ports, health checks | a deploy pipeline |
Manage watchdogs (watchdogs:manage) |
create, edit, pause, resume and delete watchdogs | a backup job that registers its own monitor |
Notifications (notify) |
publish and read notification events | CI posting build results |
Pick the least you need
Section titled “Pick the least you need”- A CI job that only posts build events: Notifications.
- A status page or dashboard: Read-only.
- An AI agent doing the whole onboarding journey: Read-only, Manage hosts, Manage services and Manage watchdogs.
A token can carry up to five scopes.
What a token can never do
Section titled “What a token can never do”- Mint or revoke API tokens. That needs you, signed in.
- Change your password or account settings.
- Manage another account, or reach another user’s resources.
This is why a leaked token cannot widen its own access.
Use it
Section titled “Use it”Send the token as a bearer credential on every request:
curl -fsS -H "Authorization: Bearer dak_your_token_here" \ https://console.dednets.com/api/v1/topologyIf the token lacks the scope for a route, the answer is a 403 that names the
scopes which would have worked:
{"error":{"code":"scope_denied","message":"this API token's scope does not cover this endpoint (token scope: read; required, any of: watchdogs:manage)","status":403,"scopes_allowed":["watchdogs:manage"]}}Scopes are fixed when the token is minted, so the fix is a new token with the extra scope.
Rotate and revoke
Section titled “Rotate and revoke”Revoke a token from the same API tokens section; revocation takes effect immediately. You can hold up to 20 tokens per account. Keep the secret in your secret manager, never in a repository. If a token leaks, revoke it and mint a replacement.