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, and custom domains (since v0.4.5), including pointing a hostname on a domain at an app (since v0.7.0), and managing who may open an app that requires a DedNets login (since v0.10.0) | a deploy pipeline |
Manage watchdogs (watchdogs:manage) |
create, edit, pause, resume and delete watchdogs | a backup job that registers its own monitor |
Manage uptime monitors (uptime:manage) |
create, edit, pause, resume and delete uptime monitors, and read their history (since v0.4.5) | a deploy pipeline that watches the site it just shipped |
Manage files (files:manage) |
share and stop sharing folders your hosts declare (since v0.8.0). It cannot create a folder, widen one past the host’s own limit, or read file content | a script that opens a folder for a transfer |
Signals (signals) |
report, list, resolve and retune signals (since v0.9.0). It cannot delete one, and it cannot mint a reporting URL | the cron job that reports a condition |
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 eight 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.
- Delete a signal, or mint a reporting URL for one. Both need you, signed in: closing a signal is reversible and a token may do it, but destroying its history is not, and neither is handing out a new credential.
- 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.