Authentication
Personal API tokens, the Authorization header and scopes.
Every request is authenticated with a personal API token sent as a bearer token:
GET /v1/me HTTP/1.1
Host: api.deluxhost.net
Authorization: Bearer dh_live_…Tokens start with dh_live_. Send them only in the header, never as a query parameter: a token in a URL ends up in access logs, proxies and browser history.
Creating a token
Tokens are created in the dashboard under Profile → Security → API tokens. Pick a name, the scopes the token needs and how long it lives: 30, 90 or 365 days, or no expiry. The token is shown once: we store only its SHA-256 hash and cannot show it again. If you lose it, revoke it and create a new one.
Creating tokens, changing your password or email, managing two-factor and anything administrative stay dashboard-only on purpose: no token can grant itself more access.
Scopes
A token can only do what its scopes allow. Read access and write access are separate scopes, and anything that can destroy data or spend money has its own opt-in scope that you have to tick explicitly:
services:reinstall,services:restore,services:consoleandservices:credentialscan erase data or hand out full access to a machine.orders:create,orders:manage,orders:cancel,billing:manageandbilling:paymove money or end services. These also requireconfirm: truein the body and anIdempotency-Keyheader.
Existing tokens never gain new scopes automatically when we add them. Each operation in the API reference lists the scope it requires.
| Scope | Grants |
|---|---|
account:read | Read your account details (name, email, credit balance). |
account:sessions | List and revoke your browser sessions. |
account:tokens:read | Read metadata of your personal API tokens; never their secrets. |
account:tokens:write | Revoke your personal API tokens; cannot create tokens or expand permissions. |
account:write | Update your personal and billing profile; cannot change login credentials. |
affiliate:read | Read your referral code and affiliate earnings. |
billing:manage | Manage automatic charging and saved payment defaults, remove saved methods and create credit top-up invoices. |
billing:pay | Pay your invoices using account credit or payment gateways, including saved payment methods. |
billing:read | Read billing settings, available gateways, saved payment method summaries and bank transfer details. |
catalog:read | Read the product catalog and prices. |
firewall:read | Read your Anti-DDoS traffic, attack history and protection rules. |
firewall:write | Create and delete Anti-DDoS protection rules on your own IPs. |
invoices:read | List your invoices and download their PDFs. |
notifications:write | Mark your notifications as read or dismiss them. |
orders:cancel | Request or withdraw cancellation of your services. Immediate cancellation may destroy data. |
orders:create | Place orders and create invoices for your account. |
orders:manage | Change service plans and billing cycles, and generate early renewal invoices. |
orders:read | Read your orders, eligible plans and billing cycles, and quote carts. |
services:console | Open a remote server console with full access to the machine. |
services:credentials | Reset the server password and send it to your account email. |
services:manage | Manage server networking, ISO media, rescue mode and backups. |
services:power | Start, restart and shut down your servers. |
services:read | List your services and read their status, specs and usage. |
services:reinstall | Reinstall a server or boot a rescue profile. Can erase all server data. |
services:restore | Restore server backups or snapshots. Can overwrite current data. |
ssh-keys:read | Read your saved public SSH keys. |
ssh-keys:write | Create, rename and remove saved public SSH keys. |
storage:files:read | List, search and download files in your Storage Boxes. |
storage:files:write | Create, edit, move, upload, archive, extract, restore and delete Storage Box files. |
storage:read | Read your Storage Boxes: usage, connection details, allowed IPs, SSH keys and snapshots. |
storage:subusers:read | Read Storage Box subusers and their permissions. |
storage:subusers:write | Create, update, remove and reset credentials of Storage Box subusers. |
storage:write | Manage your Storage Boxes: access protocols, password reset, allowed IPs, SSH keys, snapshots and rollback. |
tickets:read | Read your support tickets and customer-visible attachments. |
tickets:secrets | Manage encrypted support credentials on your own tickets; cannot reveal stored secrets. |
tickets:write | Open, reply to, close and rate your support tickets and upload attachments. |
To see what a token holds, call GET /v1/me (the scopes field) or GET /v1/scopes, which lists every scope with a granted flag.
Expiry and revocation
Revoked and expired tokens stop working on the very next request. You can revoke a token from the dashboard at any time, or from a script with account:tokens:write. Every create and revoke is recorded in your account's activity log and notified by email.
When authentication fails
| Status | code | Meaning |
|---|---|---|
| 401 | unauthenticated | The header is missing, or the token is unknown, revoked or expired. |
| 403 | permission_denied | The token is valid but lacks the scope, or the account is suspended or restricted. |
Repeated failed tokens from the same address are throttled: see Rate limits.
Something unclear or missing? Open a ticket and the team will get back to you.