Skip to content
Maran

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

CallWhat it does on the server
CreateProvisions the system user, its home and the plan's quota, then records the account
SuspendStops the sites and logins and keeps everything else; this is a state, not a deletion
ResizeMoves the quota, the worker budget and the limits to the new plan
TerminateRemoves 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:

EndpointWhoPurpose
GET /api/v1/dashboard/attention-countAdministratorHow many things need attention
GET /api/v1/serversAdministratorThe managed servers; one entry of kind local
GET /api/v1/me/accountsCustomerThe accounts the login owns
POST /api/v1/me/active-accountCustomerSwitch the active account, body {accountId}
GET, POST, DELETE /api/v1/me/pinned-pagesSigned-inRead, add and remove favourite pages
/api/v1/me/sub-usersAccount ownerInvite, change and remove team members
POST, GET, DELETE /api/v1/view-asAdministratorStart, 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:

WhereFieldValues
Account disk usagebackingenforced, notEnforced, unmeasured
PHP versionsdefaultStatusdefault, notDefault, unknown
Modulesstateenabled, locked
Dashboardaudienceadministrator, customer
FTPS servertlsEnforcementenforced, 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.