Issue a dashboard API token

Mint, scope, list, and revoke the bearer API tokens that authenticate the CLI, SDK, and external automation against the REST API v1.

This page: issue and scope a dashboard API token. Tokens are bearer credentials that authenticate the CLI, SDK, and any external automation against the REST API v1. For how a token is sent and how scope enforcement behaves, see API auth and scopes.

API tokens are a Team-plan capability and are managed by an Admin (or Owner). They live in the dashboard under Settings → API tokens.

Token model

Property	Behavior
Format	`wal_` prefix followed by hex entropy (for example `wal_…`). The prefix makes a token unambiguous in a secret-manager listing.
Plaintext	Shown once in the issue response and never recoverable afterward. The dashboard stores only a SHA-256 fingerprint, never the token.
Authentication	Sent as `Authorization: Bearer <token>` against `/api/v1`.
Scopes	A closed, least-privilege set chosen at issue time. There is no wildcard scope.
Expiry	Optional. A token can be issued with an expiry or left non-expiring.
Revocation	Revocable any time. Revoked tokens stay listed for audit history.

Every issue and revoke is recorded in the audit chain with the issuer, the token name, and the scopes — never the plaintext.

Step 1: Open the API tokens page

In the dashboard, go to Settings → API tokens (/o/<your-org>/settings/api-tokens). The page lists issued tokens with their name, scopes, creation time, last-used time, and revocation state. If you do not see the management controls, you are not an Admin, or your org is not on the Team plan.

Step 2: Issue a token

Click Issue token.
Enter a Token name that identifies where the token will run (for example terraform-ci or backup-monitor). The name is visible on this page only.
Select the scopes the token needs. Grant the minimum required — a missing scope fails closed with 403 forbidden. See the scope catalog below.
Optionally set an expiry.
Submit. The token plaintext is shown once — copy it into your secret manager before dismissing the reveal. It is never recoverable afterward.

Save the plaintext immediately

The reveal is the only time the token plaintext is shown. If you lose it, revoke the token and issue a new one — the dashboard stores only a fingerprint and cannot show it again.

Step 3: Scope the token

Scopes are coarse, org-wide, and least-privilege. Issue a token with exactly the scopes its automation needs:

Scope	Grants
`databases:read`	List and inspect protected database records.
`databases:write`	Create, update, and delete protected database records.
`destinations:read`	List and inspect configured backup destinations.
`destinations:write`	Manage backup destinations and database attachments.
`backups:trigger`	Start, cancel, and dismiss backup jobs.
`restores:read`	List and inspect restore jobs and restore-drill state.
`restores:write`	Start restore jobs and restore drills with explicit targets.
`evidence:read`	Read backup, restore, and verification evidence artifacts.
`evidence:export`	Export evidence bundles for external verification.
`audit:read`	Read audit-chain, verification, and recoverability summaries.
`readiness:read`	Read service readiness, health, and verification status.

A token with no scopes can still exercise read procedures that are scope-open in v1 (for example a read-only monitoring integration). For the per-endpoint scope matrix and the 401/403/409 semantics, see API auth and scopes.

Step 4: Use the token

Send the token as a bearer credential:

curl -H 'Authorization: Bearer $WALWARDEN_API_KEY' \
  '$WALWARDEN_BASE_URL/api/v1/databases'

The same token drives the CLI and @walwarden/sdk. Mutation endpoints require an Idempotency-Key header.

Step 5: Revoke a token

When a token is no longer needed — rotation, an offboarded integration, or a suspected leak — click Revoke on its row. Revocation is idempotent and takes effect immediately; subsequent requests with that token fail with 401 unauthorized. The revoked row stays on the page so the audit history remains complete.

API auth and scopes — bearer auth, endpoint scope matrix, idempotency
API reference — REST API v1 operations
SDK install and examples · CLI reference
Invite teammates & roles — only Admins manage tokens