Permissions
Understand which accounts and actions your API key can access.
Where to find it: Documentation > Hosting Manager > API > Permissions.
Available to: Anyone reading the public documentation. The related SHM action still follows the role stated on its page.
Before you start
Examples use placeholder accounts, domains, addresses, and credentials. Replace them deliberately, and never paste passwords, API keys, tokens, or private keys into tickets or shared notes.
Why use it — and when not to
Use Permissions to understand or plan the supported workflow. Do not treat an example as authorization or as proof of the current state on a particular SHM server.
Role model
| Role | Typical API scope | What it should not be used for |
|---|---|---|
| Root | Server-wide administration, package and available tools, account operation, reseller management, service state, security, backups, licensing, and provider operations. | Do not use root keys for customer-owned integrations that only need one account. |
| Reseller | Delegated customer accounts, reseller package limits, account account creation where allowed, and support workflows for owned accounts. | Do not use reseller keys to change server-wide services, licensing, root-only security, or unrelated reseller accounts. |
| User | The authenticated account surface: domains, DNS, SSL, files, mail, databases, backups, logs, resource usage, runtimes, and allowed self-service tools. | Do not use user keys for other accounts or provider-level policy. |
Permission checks
- Path ownership is checked for account endpoints that include {username}.
- Reseller operations are limited to delegated accounts and package policy allowed by the provider.
- Root-only endpoints can affect server-wide state and should be restricted to trusted automation.
- Feature profiles and packages can hide or deny tools even when the account exists.
- State-changing operations should be audited by the calling system with target, operator, request time, and result.
Choosing a scope
| Integration need | Recommended API scope |
|---|---|
| Billing platform creates and suspends customer accounts | Root API or a carefully limited reseller API if the provider delegates account creation. |
| Reseller portal manages owned accounts | Reseller API. |
| Customer portal edits DNS, mailboxes, SSL, backups, or files for one account | User API. |
| Monitoring checks service status or resource pressure | Root API for server status; User API for one customer account. |
| Support dashboard inspects logs, delivery reports, backups, and resource state | Use the narrowest role that can see the target customer. |
How to use it
- Check which role and account are assigned to your API key.
- Compare them with the access requirements of the action you want to use.
- Ask the administrator for the necessary access if the request is denied.
Explicit reseller routes and long-running operations
The public reference now includes the explicit /v1/resellers/{reseller}/... namespace. It makes reseller scope visible in the URL while preserving ownership, capacity, feature, and source-policy checks. A reseller may target only its own identifier; root may select an authorized reseller.
Long-running service, Compose, migration, backup, and restore workflows can return an operation/task identifier. Follow the corresponding status/log endpoint and preserve terminal errors. Do not equate an accepted or queued operation with a completed result.
Theme color