How it works
The provisioning API
How a billing system creates, suspends, resizes and terminates hosting accounts without a person in the loop, and how an integration authenticates today.
Maran is meant for selling hosting, so the billing system that takes the money has to be able to drive it. This page covers what that system can call.
A login, not a key yet
A billing system authenticates today as a login: it signs in at POST /api/v1/auth/login and
sends the access token it receives as a bearer token. The token is short-lived (15 minutes by
default) and is renewed at POST /api/v1/auth/refresh. The account lifecycle below needs an
administrator login, so give the integration a login of its own rather than a person's: its
sessions can then be ended on their own, and its calls are told apart in the audit journal.
Scoped API keys, which would let a key provision accounts without reaching anything else, are not built yet. Until they are, the integration's login has the administrator's full reach, and every call it makes is recorded in the audit journal alongside what people do.
The account lifecycle
| Call | What it does on the server |
|---|---|
| Create | Provisions the system user, its home and the plan's quota, then records the account |
| Suspend | Stops the sites and logins and keeps everything else; this is a state, not a deletion |
| Resize | Moves the quota, the worker budget and the limits to the new plan |
| Terminate | Removes databases, logins and the jail, ends the account's processes, then removes the user. It aborts instead of leaving orphans |
The calls are POST /api/v1/accounts, POST /api/v1/accounts/{id}/suspend (and /reactivate),
PUT /api/v1/accounts/{id}/plan and DELETE /api/v1/accounts/{id}. Each is the same operation the panel's own screens perform. There is no separate path for machines:
the API and the interface call the same code, so they cannot disagree about what suspension means.
Plan features, accounts and views
A plan create or update requires a features list: the full set the plan sells, which an update
replaces. An empty list sells none, and a request that leaves the list out is refused.
GET /api/v1/plans/features lists the available features (administrator).
A few endpoints serve the panel's own screens and are listed here for completeness:
| Endpoint | Who | Purpose |
|---|---|---|
GET /api/v1/dashboard/attention-count | Administrator | How many things need attention |
GET /api/v1/servers | Administrator | The managed servers; one entry of kind local |
GET /api/v1/me/accounts | Customer | The accounts the login owns |
POST /api/v1/me/active-account | Customer | Switch the active account, body {accountId} |
GET, POST, DELETE /api/v1/me/pinned-pages | Signed-in | Read, add and remove favourite pages |
/api/v1/me/sub-users | Account owner | Invite, change and remove team members |
POST, GET, DELETE /api/v1/view-as | Administrator | Start, read and end viewing as an account |
Answers without a body
A change that has nothing to report answers 204 No Content with no body. It used to answer 200
with the body true, which added nothing to the status code. A client that parsed the body must
stop doing so, and a client that checks for success should accept any 2xx. This covers:
- identity: sign-out, password change, session revocation, invitations, sub-users, the security policy and ending view-as;
- plans and backups: delete;
- cron: update, enable or disable, delete and the environment;
- databases, sites and certificates: delete and remove;
- firewall: allow, deny, ban, unban and whitelist removal;
- FTPS and SFTP users: delete;
- outgoing mail: save and send a test;
- the log level.
Renamed response fields
A field that used to say yes or no, for something that can also be unknown, now names each case:
| Where | Field | Values |
|---|---|---|
| Account disk usage | backing | enforced, notEnforced, unmeasured |
| PHP versions | defaultStatus | default, notDefault, unknown |
| Modules | state | enabled, locked |
| Dashboard | audience | administrator, customer |
| FTPS server | tlsEnforcement | enforced, notEnforced, notObserved |
The health report no longer carries a top-level status; read the agent and database entries
instead.
What it is not
The API is not a way to run commands on the server. It reaches the agent only through the typed operations the agent already accepts, the same closed set the panel uses. A caller cannot ask for a shell, because nothing on the other side accepts one.
Errors say what a caller may know
A resource that belongs to an account the caller does not act for answers not found, never forbidden. A "forbidden" would confirm that the resource exists, which the caller is not entitled to know.
Creating the same database twice reports that it exists and leaves the first password working. A retry after a lost response must not invalidate a credential the customer has already been shown.
An endpoint that declares no access rule is closed to customers. An anonymous caller is refused with 401, a signed-in customer with 403 and an empty body, and only an administrator is admitted. The same holds for a path that matches no endpoint: a customer gets 403 there, not 404. Every endpoint names its rule explicitly; this default only guards against a mistake and should not be relied on.
Every error code
Each refusal carries a machine-stable code beside a sentence in the caller's language. The full
list, with the HTTP status of each code, is on API error codes.