API Authentication
All DanubeData API requests require authentication using Laravel Sanctum bearer tokens.
Creating an API Token
Step 1: Open Security, API tokens
- Log in to your DanubeData account
- Open Security from the account menu in the top right (the sidebar calls it Credentials)
- Open the API tokens tab
Step 2: Create a New Token
- Click Create token
- Enter a descriptive name for the token (e.g., "Production Server", "CI/CD Pipeline")
- Choose its Project access: This project only (default) or All your projects (see Project Scope)
- Tick the permissions it needs. They are grouped by resource; Defaults, Select all and Clear set them all at once. The form lists only what your role allows (see Roles and Tokens)
- Click Create token, then confirm it's you when asked
Step 3: Save Your Token
Important: The token will only be shown once. Copy it immediately and store it securely.
Token: 7TEwyZaQXMXRVBZV9USjWNRbXAbPv9BrgMJSLDCk345196d2
Using Your Token
In HTTP Headers
Include the token in the Authorization header with the Bearer prefix:
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
https://danubedata.ro/api/v1/vps
The scheme name is case-insensitive (bearer works too), and a token works only with the API, never with console pages, which refuse it with a 401.
Example with cURL
curl -X GET \
'https://danubedata.ro/api/v1/vps' \
-H 'Authorization: Bearer 1|7TEwyZaQXMXRVBZV9USjWNRbXAbPv9BrgMJSLDCk345196d2' \
-H 'Accept: application/json'
Example with JavaScript/Axios
const axios = require('axios');
const api = axios.create({
baseURL: 'https://danubedata.ro/api/v1',
headers: {
'Authorization': 'Bearer YOUR_TOKEN_HERE',
'Accept': 'application/json'
}
});
// Make a request
api.get('/vps')
.then(response => console.log(response.data))
.catch(error => console.error(error));
Example with Python
import requests
headers = {
'Authorization': 'Bearer YOUR_TOKEN_HERE',
'Accept': 'application/json'
}
response = requests.get(
'https://danubedata.ro/api/v1/vps',
headers=headers
)
print(response.json())
Example with PHP
<?php
$token = 'YOUR_TOKEN_HERE';
$url = 'https://danubedata.ro/api/v1/vps';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $token,
'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);
Token Permissions
Tokens can have different permission scopes. Each is {resource}:{action}, and you choose them when you create the token.
Available Scopes
| Resource | Read | Write | Delete | Other |
|---|---|---|---|---|
| VPS instances and block volumes | vps:read | vps:write | vps:delete | vps:diagnostics, vps:credentials |
| Databases | database:read | database:write | database:delete | database:diagnostics, database:credentials |
| Caches | cache:read | cache:write | cache:delete | cache:diagnostics, cache:credentials |
| Queues | queue:read | queue:write | queue:delete | queue:diagnostics, queue:credentials |
| Parameter groups | parameter-group:read | parameter-group:write | parameter-group:delete | |
| Firewalls | firewall:read | firewall:write | firewall:delete | |
| Snapshots | snapshot:read | snapshot:write | snapshot:delete | |
| SSH keys | ssh-key:read | ssh-key:write | ssh-key:delete | |
| Webhooks | webhook:read | webhook:write | - | |
Secrets API (/api/secrets) | secret:read | secret:write | - | |
| Object storage | storage:read | storage:write | storage:delete | storage:diagnostics |
| Managed apps | app:read | app:write | app:delete | app:diagnostics, app:credentials |
| Uptime checks | uptime:read | uptime:write | uptime:delete | |
| Resource alerts | resource-alert:read | resource-alert:write | resource-alert:delete | |
| Metric alerts (the older name of resource alerts, still accepted) | metric-alert:read | metric-alert:write | metric-alert:delete | |
| Container registry | registry:read | registry:write | registry:delete | registry:credentials |
| Serverless containers (Rapids), with their volumes, backups and restores | serverless:read | serverless:write | serverless:delete | serverless:diagnostics |
| Static sites | static-site:read | static-site:write | static-site:delete | static-site:diagnostics |
| Managed Kubernetes | kubernetes:read | kubernetes:write | kubernetes:delete | |
| Audit log | audit:read | - | - | audit:export, audit:raw |
| Support tickets | support:read | support:write | - | |
| Account limits | - | - | - | account-limits:request |
- Read views and lists. Write creates, changes and acts. Delete deletes.
{resource}:diagnosticsis separate from:readon purpose: a token that may list your databases cannot read what they print to their logs unless you also grant it.app:credentialsreturns a managed app's working admin password, so it is separate fromapp:read. The same holds forvps:credentials,database:credentials,cache:credentialsandqueue:credentials: see Reading passwords.secret:readreads the values stored through the Secrets API andsecret:writecreates, changes and deletes them.registry:readlists the registry's access keys andregistry:credentialscreates (its token is returned once) and revokes one: see Reading passwords. Only the project owner manages access keys.registry:writeis reserved: repositories are created by pushing an image, so nothing writes through the API yet.account-limits:requestlets a token ask for higher account limits and read the status of that request. It changes nothing by itself: the request waits for the project owner to approve it in the console. See Requesting with an API token.support:readandsupport:writeopen the Support Tickets API. A ticket opened or a reply sent with a token is marked as such, and support verifies the sender before changing anything or sharing account data.- New tokens start with read access to VPS, databases, caches, storage and static sites:
vps:read,database:read,cache:read,storage:readandstatic-site:read. Nothing else is on by default. - A token keeps the abilities it was created with. One you made before an ability existed does not get it: open the token on Security, API tokens, tick it and save, or create a new token. The exception is a token with all abilities, such as the one
danube authcreates when you are an owner or Administrator in all your projects: it holds every ability, ones added later included. - What a token holds is only half of what it can do: the role of the person who made it decides every call too. See Roles and Tokens.
Reading passwords
read never includes a password. The routes that return a working password need a separate credentials permission, so a token that only lists or monitors a resource cannot come away with the keys to it.
| Permission | What it unlocks |
|---|---|
vps:credentials | GET /api/v1/vps/{id}/password, the root password |
database:credentials | GET /api/v1/database/{id}/credentials, the superuser and application passwords |
cache:credentials | GET /api/v1/cache/{id}/credentials, the cache password |
queue:credentials | The password in GET /api/v1/queue/{id}/connection-info |
app:credentials | GET /api/v1/apps/{id}/credentials, the admin password |
registry:credentials | POST /api/v1/registry/access-keys, a new registry access key and its token, and DELETE /api/v1/registry/access-keys/{id} |
Without the permission on the token, or when your role cannot read that password, a route that exists to return a password answers 403.
Each time a token is handed a password, your project's Activity Log gets an entry that names the token and the resource, so a token that should not be reading passwords shows up there. A token that reads the same password again within ten minutes is one entry, and the password itself is never written to the log. Reading a password from the console is not an API token read and is not logged this way.
The routes that describe how to connect stay open to read: GET /api/v1/cache/{id}/connection-info, GET /api/v1/queue/{id}/connection-info, and GET on the database, cache and queue instance itself. Without the credentials permission they leave the secret out. password, and any connection URL (connection_info, amqp_url, which contains the password), come back as null. The host, port, username and vhost are still there.
Your role decides which password permissions a token can use. The owner and Administrators can read every password. An Editor can read database, cache and queue passwords, so database:credentials, cache:credentials and queue:credentials can go on an Editor's token. vps:credentials and app:credentials cannot: the VPS root password and a managed app's admin password (Storage Share and Immich included) stay with the owner and Administrators. A token that can act in all of your projects gets a password permission only if your role allows it in every one of them. The token danube auth creates is an all-projects token too, so it follows the same rule. The role is checked each time the token is used, as well as when it is made, so a token that holds a password permission your role does not allow is refused: see Roles and Tokens.
Starting a database password rotation needs database:write. Reading the new password, or polling credential_rotation, is GET /api/v1/database/{id}/credentials, so it needs database:credentials as well.
The Secrets API returns the values you stored in it, so it has the same split: secret:read reads them (add ?include_value=true to get the values) and secret:write creates, changes and deletes them. Neither is on by default and neither implies the other. The Secrets API lists what you stored: the passwords DanubeData generated for your databases, caches and apps are not in it, and are read from each resource's credentials route with the permission above.
None of these permissions is on by default. Select them when you create a token that has to read passwords. Tokens that already existed and had not expired were given what they could use before: the matching credentials permission for each resource they could read, and secret:read and secret:write. Automation that already read passwords or secrets keeps working, as long as the role of the person who made the token allows the call. If a token does not need to, open it on Security, API tokens and untick the permission.
Principle of Least Privilege
Always create tokens with the minimum permissions required for their purpose:
- Read-only tokens for monitoring and reporting
- Write tokens only for automation that needs to create/modify resources
- Separate tokens for different services/environments
- A token of its own for each AI agent you connect to the MCP server, so you can revoke one agent without touching anything else
support:writeonly where it is needed, because what a token sends is not something we can treat as coming from a person you know
Roles and Tokens
A token acts for the person who made it, so it never does more than their role allows. Every call has to pass two checks:
- The token holds the permission the call needs, such as
vps:delete. - The role of the person who made the token allows the call, in the project the call acts on.
A call that fails the first check answers 403 and names the permission to add:
{
"message": "This token does not have the vps:delete ability. Add it to the token under Security, API tokens."
}
A call that fails the second check answers 403 and names the role:
{
"message": "Your role in this project (Editor) does not allow vps:delete. Ask the project owner to change your role."
}
Ticking more permissions on the token does not help when the role refuses: only a different role does. When a call fails both checks, the answer is the role's. The CLI and the MCP tools make the same API calls, so the same two checks apply to them.
The permission in a role message is the one your role must hold, and it can differ from the one the token needs. Reinstalling a VPS, restoring a snapshot over a resource and restoring a Rapids volume backup over a volume replace the data that is there, so they count as deleting for your role (vps:delete, database:delete, serverless:delete and so on). The token still asks for what it asked for before: vps:write for a reinstall, snapshot:write for a snapshot restore, serverless:write for a volume restore.
What each role allows
The table under Team Member Roles lists what each role can do. For a token it comes to this:
- The owner and Administrators can use every permission a token can hold, except four that act on the project itself:
project:write,project:invite,project:deleteandproject:members:deletework only for the owner. See the Project API. - An Editor's token cannot use any
:deletepermission except the two below, norvps:credentials,app:credentials,audit:export,audit:raw,partner:readorpartner:write. Everything else works, includingdatabase:credentials,cache:credentialsandqueue:credentials. - Two
:deletepermissions are still offered to an Editor, because two things an Editor may do ask the token for them:storage:delete(revoking an S3 access key) andstatic-site:delete(removing a custom domain). They do not let an Editor delete a bucket or a site: the role refuses that. - A Viewer's token can use the
:readpermissions of the project's resources and nothing that changes anything. It cannot read passwords or secrets, webhooks, logs or the audit log. - A Billing member's token holds no project permission at all: billing has no token permission, so it is managed in the console. It can still use
project:*where the owner allowed it,ssh-key:*andsupport:*. ssh-key:*andsupport:*belong to the person, not to a role, so they work with any role.
When a role changes
A token keeps the permissions it was made with, but the role decides each call. If the owner demotes you, your tokens lose whatever your new role does not allow on your next call. If you are promoted, your tokens can use at once what they already hold and the new role allows. A token does not gain permissions it was not made with: tick them on the token.
A token that holds permissions your role does not allow says so: its page under Security, API tokens marks them Not allowed by your role. Untick them and save, or ask the owner to change your role.
What the token form offers
The form lists only the permissions your role allows, in every project the token can reach:
- A token for This project only is judged by your role in that project.
- A token for All your projects gets a permission only if your role allows it in each project you belong to. Being an Editor in one project leaves what an Editor cannot do off the whole token. The same goes for a Viewer or Billing role in any one project: it leaves every write, or every project permission, off your new
danube authtokens, including for projects you own.
The token danube auth creates is a token for all your projects, so it follows the same rule. It holds every permission, ones added later included, when you are an owner or Administrator in all your projects. Otherwise it holds what your roles allow in all of them, and none added later. The sign-in page then says What your roles allow.
Project Scope
In addition to permission scopes, every token is bound to a project scope that controls which of your projects it can touch. Choose the scope when you create the token:
- This project only (default for new tokens) — the token is locked to the project you created it in and can never act on any other project. Ideal for a single integration or environment.
- All your projects — an account-wide token that can act on any project you belong to.
The Project column of the token list shows the project a token is locked to, or All your projects. A token locked to a project you have since left is refused, and the list says A project you have left.
Selecting a project with an account-wide token
An account-wide token acts on your current project by default: the one you last switched to in the console. To target a specific project, send its ID in the X-Team-Id header:
curl -H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Team-Id: 42" \
https://danubedata.ro/api/v1/vps
With an account-wide token, one request acts on one project: the one in X-Team-Id, else your current project. Your role in that project decides the call. A resource that belongs to a different project answers 404 Not Found, even when you are a member of both projects, so send X-Team-Id for the project the resource is in.
A script that works in several projects with one account-wide token should send X-Team-Id on every call. Without it, each call acts on whichever project you last switched to in the console. The Terraform provider sends it when you set team_id in its provider block, or DANUBEDATA_TEAM_ID (version 0.4.0 and later): see Terraform. An integration that cannot send the header should use a token locked to its project.
Project-locked tokens
A project-locked token ignores any project other than the one it is bound to. If you send an X-Team-Id for a different project, the request is refused:
{
"message": "This token is scoped to a single project and cannot access the requested team.",
"error": "Forbidden"
}
Asking a project-locked token for a resource of another project is refused with 403, or with 404 Not Found where the endpoint looks the resource up within the project (VPS, buckets and static sites, for example).
Existing tokens keep working. Tokens created before project scoping remain account-wide (All your projects) — nothing changes unless you choose to tighten them by creating a new project-locked token. Like any account-wide token, they act on one project at a time, as described above.
Managing Tokens
Viewing Active Tokens
The API tokens tab on Security lists your tokens with:
- Token name
- The project it reaches
- A summary of its permissions
- Last used date
Open a token to see when it was created and when it expires, and to change its permissions. A token made by danube auth holds every permission, including any added later, when you are an owner or Administrator in all your projects; otherwise it holds what your roles allow in all of them, and none added later. Saving a change to it keeps only what is ticked.
Revoking Tokens
To revoke a token:
- Open it on the API tokens tab
- Click Delete
- Confirm the deletion
Warning: Revoking a token immediately invalidates it. Any services using that token will stop working.
Security Best Practices
Storage
- Never commit tokens to version control
- Store tokens in environment variables or secure vaults
- Use different tokens for different environments (dev, staging, prod)
Rotation
- Rotate tokens regularly (e.g., every 90 days)
- Immediately revoke tokens when:
- An employee leaves
- A service is decommissioned
- A token may have been compromised
Monitoring
- Check token usage regularly on the API tokens tab
- Investigate any unexpected "Last used" dates
- Set up alerts for unusual API activity
Authentication Errors
401 Unauthorized
Error Response:
{
"message": "Unauthenticated."
}
Causes:
- Missing
Authorizationheader - Invalid token format
- Revoked or expired token
Solution:
- Verify the token is included correctly
- Check the token hasn't been revoked
- Create a new token if needed
403 Forbidden
Error Response:
{
"message": "This token does not have the vps:delete ability. Add it to the token under Security, API tokens."
}
Causes:
- The token lacks the permission the call needs (the message above)
- Your role does not allow the call:
Your role in this project (Editor) does not allow vps:delete. Ask the project owner to change your role.(see Roles and Tokens) - Using a project-locked token against a different project (see Project Scope)
- The action is not open to your role at all, such as one only the project's owner may take:
This action is unauthorized.
Solution:
- If the token lacks the permission, open it on Security, API tokens, tick the permission and save, or create a new token
- If your role refuses, ask the project owner to change your role, or have an Administrator make the call. More permissions on the token do not help
- If the token is project-locked, use it only against its own project, or create an All your projects token
404 Not Found
A resource of another project answers 404, even when you are a member of both projects. Check the ID, and send X-Team-Id for the project the resource is in (see Project Scope).
Testing Authentication
In the Interactive Docs
- Visit
/docs/apiin your browser - Click the Authorize button (top right)
- Enter:
Bearer YOUR_TOKEN_HERE - Click Authorize
- Try any endpoint to verify it works
Using cURL
# Test with a simple endpoint
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://danubedata.ro/api/v1/vps
# Should return your VPS instances or an empty array
Next Steps
- Visit
/docs/apito explore all authenticated endpoints - Learn about rate limits
- Set up webhooks for event notifications