Reference
API auth and scopes
Generated guide for API key authentication and endpoint scopes.
Use a scoped Walwarden API key with the HTTP bearer scheme:
curl -H 'Authorization: Bearer $WALWARDEN_API_KEY' \
'$WALWARDEN_BASE_URL/api/v1/databases'Issue, scope, and revoke these keys from the dashboard — see Issue a dashboard API token.
Missing, inactive, or expired keys return 401 unauthorized. Keys without the endpoint scope return 403 forbidden with requiredScope and nextAction in the structured error body.
Mutation endpoints require an Idempotency-Key header. Reusing a key with a different request body returns 409 conflict.
Scopes Used By Public API v1 Alpha
| Scope | Label | Description |
|---|---|---|
databases:read | Read protected databases | List and inspect protected database records. |
destinations:read | Read backup destinations | List and inspect configured backup destinations. |
backups:trigger | Trigger backup jobs | Start, cancel, and dismiss backup jobs. |
restores:read | Read restore jobs | List and inspect restore jobs and restore-drill state. |
restores:write | Run restore jobs | Start restore jobs and restore drills with explicit targets. |
evidence:read | Read evidence bundles | Read backup, restore, and verification evidence artifacts. |
Endpoint Scope Matrix
| Method | Path | Operation | Required scope |
|---|---|---|---|
GET | /profile | getProfile | none |
GET | /databases | listDatabases | databases:read |
GET | /databases/{databaseId} | getDatabase | databases:read |
GET | /destinations | listDestinations | destinations:read |
GET | /destinations/{destinationId} | getDestination | destinations:read |
GET | /databases/{databaseId}/backups | listDatabaseBackups | databases:read |
POST | /databases/{databaseId}/backups | triggerBackup | backups:trigger |
GET | /backups/{backupJobId} | getBackup | databases:read |
GET | /evidence | listEvidence | evidence:read |
GET | /evidence/{backupJobId} | getEvidence | evidence:read |
POST | /restores | createRestore | restores:write |
GET | /restores/{restoreJobId} | getRestore | restores:read |
GET | /databases/{databaseId}/recovery/summary | getRecoverySummary | databases:read |
GET | /databases/{databaseId}/recovery/candidate | getRecoveryCandidate | databases:read |
GET | /recovery/windows/{windowId}/proof | getRecoveryWindowProof | databases:read |