Cloudpress API

Verified against CloudPress platform release 2026.08.01.

When to Use This Skill

Activate this skill when:

• User asks how to call a specific CloudPress API endpoint
• User asks what parameters an endpoint accepts or what a response looks like
• User asks about authentication, API keys, OAuth, scopes, or the X-Auth-Account header
• User asks about permissions, roles, or what their token can do
• User is debugging a 400, 401, 402, 403, 404, 409, 422, 429, 502, or 503 from the API
• User asks about async operations, task polling, registrar processes, or completion callbacks
• User asks about billing webhooks (outbound site-subscription lifecycle webhooks configured on a billing plan) — what events fire, the payload shape, or why a domain/registrar event didn't produce one
• User asks about cPanel hosting accounts through the API — ordering, resizing, domains, passwords, control-panel sessions
• User asks about Mailspace mail hosting through the API — ordering or resizing a mailspace, or managing what is inside one: mailboxes, app passwords, mail rules, vacation responses, aliases, groups, mailing lists, masked emails, mail domains and their ownership verification, deleted-mail recovery, or delivery logs
• User asks about a WordPress site's transactional email through the API — sender settings, send logs, mail metrics, or the sender-DNS check
• User asks how to set up, configure, or connect the CloudPress MCP server (e.g. in Claude Desktop/Cowork), what MCP tools exist, or why an MCP token is rejected
• User is building an integration with CloudPress

CloudPress REST API

Authentication

All /api/* requests authenticate via an HTTP Bearer token:

Authorization: Bearer <token>

There are three credential types, all presented as a Bearer token. The server resolves which kind it is (session/API key first, then OAuth).

Account scoping — X-Auth-Account:

X-Auth-Account: <account_guid>

Scopes a user API key to a single account: index endpoints then return only that account's resources, instead of resources across every account the token's user can access.

The endpoints that require the header answer 400 {"errors":["Missing X-Auth-Account"],"code":"missing_account"} when it is absent. That set is exactly:

• every route under /api/orders (including POST /api/orders/domain), /api/subscriptions, /api/carts, /api/users, /api/domain_contacts, /api/domain_registrations (including its nested hosts and processes), and /api/cpanel_accounts (including its nested password, purge, session and domains)
• POST /api/sso
• POST /api/dns_zones — zone create only; its body carries no code key, just {"errors":["Missing X-Auth-Account"]}
• POST /api/mailspace — mailspace create only; it answers 400 with code: "account_required" and a longer message. The two codes mean the same thing on different routes. The nested /api/mailspace/:mailspace_id/… routes do not inherit this: sent without the header, they resolve the mailspace from the ones the token's user can reach, and an inaccessible guid is a 404 with an empty body — deliberately indistinguishable from one that does not exist.

Nothing else requires it. In particular the webhook endpoints do not: GET /api/webhooks/task needs no account at all, and POST /api/webhooks/task/:id has no header check — called with no account context it fails inside the action and returns a 500, not a 400.

OAuth tokens always carry an account, so the header is irrelevant for them.

Authentication failures return 401 with header WWW-Authenticate: Token realm="Application" and an empty body. Causes: no/invalid token, IP not on the access list, the resolved account is on trial, or the X-Auth-Account GUID doesn't match an account the token can access. Trial accounts cannot use the API at all (both session and OAuth auth reject them; a user-API-key call with no X-Auth-Account resolves no account and so isn't trial-blocked at auth time).

There are three 401 body shapes:

1. the empty body above — also what DELETE /api/accounts/:id returns when the caller is refusing to delete their only remaining account;
2. {"error":"invalid_token","error_description":"..."} for an audience-bound OAuth token (next paragraph);
3. {"errors":["This endpoint requires a user-scoped API key."],"code":"user_required"} from the endpoints that need a user behind the credential (see Scopes).

Audience-bound OAuth tokens: an OAuth access token minted with a resource (RFC 8707 audience, e.g. for /mcp) is rejected at /api/* with 401 {"error":"invalid_token","error_description":"token audience is not valid for /api"}. Only un-audienced (or /api-audienced) tokens work here.

Rate limiting: 600 requests / 10 minutes. Two details that are easy to get wrong:

• The budget is keyed on the client IP, not on the credential — several tokens behind one egress IP share one bucket.
• It is counted per resource group, not once across all of /api — sites, domains and DNS each get their own 600, so exhausting one leaves the others untouched.

Exceeding it returns 429 with an empty body.

The /mcp endpoint is the opposite on both counts: 6000 requests / 10 minutes, keyed on the OAuth access token (falling back to the client IP when there is no token), so LLM clients sharing egress IPs don't collide.

OAuth 2.1

CloudPress runs a standard OAuth 2.1 authorization server. Use it for third-party apps acting on a user's behalf; use API keys for first-party/server integrations.

Authorization server metadata (per-brand, derived from request host):

GET /.well-known/oauth-authorization-server

{
  "issuer": "https://<host>",
  "authorization_endpoint": "https://<host>/oauth/authorize",
  "token_endpoint": "https://<host>/oauth/token",
  "revocation_endpoint": "https://<host>/oauth/revoke",
  "introspection_endpoint": "https://<host>/oauth/introspect",
  "registration_endpoint": "https://<host>/oauth/registration",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["sites:read","sites:write","domains:read","domains:write","dns:read","dns:write","mailspace:read","mailspace:write","billing:read","cpanel:read"],
  "service_documentation": "https://<host>/docs/oauth"
}

• Grant types: authorization_code and refresh_token only. PKCE is mandatory (S256 only). Refresh tokens rotate (previous token revoked on use).
• No OpenID Connect — there is no /.well-known/openid-configuration, no userinfo endpoint, and no ID tokens. The only OIDC-adjacent surface CloudPress exposes is Dynamic Client Registration (below).
• Dynamic Client Registration (DCR, RFC 7591): POST /oauth/registration. This server only ever issues public PKCE clients, but it does not reject a registration that asks for a confidential token_endpoint_auth_method — the requested value is coerced to "none" and the registration succeeds as a public client, echoing "none" back with no client_secret. So a client that sends client_secret_post (as some connector implementations do regardless of the advertised metadata) registers successfully and then uses PKCE. Per-IP limit: 50 registrations/hour → 429 {"error":"too_many_requests","error_description":"registration rate limit exceeded"}.
• Brand isolation — OAuth tokens only: an OAuth access token is bound to the brand (hostname) it was issued under and is rejected on any other brand's hostname. The authorize screen only lists the user's non-trial accounts on the current brand. API keys and session tokens are not brand-checked — they authenticate on any brand host.

Scopes

There are no default scopes — every resource scope is opt-in. The complete vocabulary:

GET /api/about accepts any valid token regardless of scope.

There is no cpanel:write scope and no billing:write scope. Do not read that as "OAuth cannot spend the account's money" — it can.

• What the missing scopes really cover. Direct order placement (POST /api/orders, POST /api/orders/domain, POST /api/domain_registrations/:id/registrant_change) and the cPanel writes (account order/resize/cancel, password, purge, control-panel session, domain add/remove) declare no scope at all, so they fail closed for every OAuth token. That much is true.

• What is NOT covered — read this before granting either scope. Two scopes that do exist reach a purchase:

  • mailspace:write → POST /api/mailspace buys a new mailspace, and PATCH /api/mailspace/:id resizes one.
  • sites:write → PATCH /api/sites/:id with a plan parameter changes the site's plan (an up- or downgrade of the recurring subscription).

  Each of those builds a cart and charges the account's saved default payment method off-session — no interactive confirmation step, no separate billing scope, and the 202 comes back whether the charge succeeded or was declined.

Consequence: an OAuth token holding mailspace:write or sites:write can spend the account's money and change its recurring bill. Treat those two as billing-capable when deciding what to request or grant. Only the order-placing and cPanel endpoints listed above are genuinely out of OAuth's reach.

A second consequence — data access, not only money. The two mailspace scopes are often assumed to cover subscription metadata. They do not:

• mailspace:read reaches mail itself. It lists a mailspace's mailboxes, reads its delivery logs, and — where the mail platform's archive feature is available — lists a mailbox's deleted mail and downloads a raw message.
• mailspace:write reaches irreversible destruction. Mailbox force-delete erases the mail the ordinary restore path exists to bring back, and the mailspace purge destroys a soft-deleted mailspace immediately rather than at the end of its retention window.

There is no narrower mail scope to request instead, and no separate scope for either capability. Grant mailspace:read only where reading a customer's mail is intended, and mailspace:write only to a client that genuinely administers mail.

Endpoints unavailable via OAuth (no scope declared → fail-closed): account CRUD & roles, API keys, users, user_roles, global tasks, SSO (site and top-level), webhooks, the domain-order endpoints (POST /api/orders/domain, POST /api/domain_registrations/:id/registrant_change), every cPanel write (account order/resize/cancel, password, purge, control-panel session, domain add/remove), and POST/PATCH/DELETE on /api/orders. These require a session or API-key credential.

Several of those blocked endpoints additionally reject a system account-bearer key (an account with no user) with 401 {"errors":["This endpoint requires a user-scoped API key."],"code":"user_required"}. The endpoints that do this are: POST /api/orders/domain, POST /api/domain_registrations/:id/registrant_change, POST /api/cpanel_accounts, PATCH/DELETE /api/cpanel_accounts/:username, and the nested cPanel password, purge, session, and domain create/destroy endpoints.

Scope enforcement

Session and API-key credentials bypass scope checks entirely. For OAuth tokens:

• Missing the required scope → 403, header WWW-Authenticate: Bearer error="insufficient_scope", scope="<required>", body {"error":"insufficient_scope","error_description":"requires scope: <required>"}.
• Endpoint declares no scope (OAuth-blocked) → 403 {"error":"insufficient_scope","error_description":"endpoint not available via OAuth"}.

Removing a user's role on an account revokes their OAuth tokens and sessions for that account.

Base URL & Conventions

• Host: https://my.cloudpress.com is the default CloudPress host, and every example in this document uses it. White-label brands are served on their own hostname (e.g. brand.example.com) with identical paths — substitute your brand's host throughout, including the /mcp and /oauth/* URLs. Brand-locking applies to OAuth access tokens only — one issued on a given brand's hostname is rejected on any other. API keys and session tokens are not brand-checked and authenticate on any brand host.
• All API routes are under /api/. All responses are JSON.
• Resource IDs are GUIDs (UUID format). The complete list of exceptions:
  • task IDs, volume IDs, DNS record-type codes and domain_contact IDs are integers;
  • a cPanel account is addressed by its cPanel username (/api/cpanel_accounts/:username);
  • a cPanel domain is addressed by the domain name (/api/cpanel_accounts/:username/domains/:id);
  • a registrar host is addressed by its host name (/api/domain_registrations/:id/hosts/:host_name);
  • a cart is addressed by an opaque token, not a GUID (/api/carts/:token).
• Timestamps are ISO 8601, UTC.
• Async operations return 202 Accepted, but the body varies by endpoint — see Async Patterns for the enumerated shapes and what to poll.
• Pagination: exactly five index endpoints paginate — GET /api/domains, GET /api/subscriptions, GET /api/dns_zones, GET /api/orders, and GET /api/cpanel_accounts. They accept page and per_page (default 50, max 100; values outside 1..100 are clamped). Every other index endpoint ignores page and per_page and returns the full set — don't build a pager against them.

Error Responses

Note: there is no longer a generic domains/backups "feature flag → 503" model. DNS, domains, backups, and restores are no longer feature-flag gated. The only FeatureFlag 503 in the API is the domain-registration flag. CDN/Shield availability is signaled by 409 (cdn_not_active/shield_not_active), and Shield plan access by 403 (shield_not_in_plan/shield_premium_required).

Common error messages:

Authorization & Account Model

Many 401/403 errors come from token scope or role gaps.

Account Types

Brands: resellers can white-label via an AccountBrand (hostname, name, logo, theme, SMTP, support contacts). Each account belongs to a brand; the brand is resolved from the request hostname and isolates OAuth tokens.

Role Permission Flags

Every user has a role on each account they belong to. Flags on the role:

A suspended user fails every permission check. List available roles: GET /api/user_roles.

Role Inheritance

A user granted a role on a parent account automatically receives the same role on all child accounts (cascaded asynchronously). Inherited roles carry inherited_from in the response and cannot be removed at the child level — change the parent role to update all descendants (deleting an inherited role returns 422).

Permission Check Flow

1. Is the token valid, IP allowed, account not on trial, not rate-limited?
2. For OAuth tokens: does the token's scope cover this action? (Session/API keys skip this.)
3. Is X-Auth-Account required by this endpoint?
4. Does the token's user have the required role flag on the target account?
5. For reseller-only operations: is the account a reseller?
6. For per-site tool endpoints: is the site dunning-suspended? (→ 402)

Reseller Capabilities

With a reseller account and X-Auth-Account set to it:

• POST /api/accounts — create sub-accounts
• POST /api/users — create managed users (returned with an auto-generated password and API token)

Sub-accounts inherit the reseller's billing plan.

Dunning Suspension

When a site's invoice is unpaid, per-site show/update/destroy and tool endpoints return 402:

{
  "errors": ["This service is suspended because an invoice is unpaid."],
  "code": "service_suspended",
  "invoice": { "number": "INV-123", "hosted_url": "https://..." }
}

List endpoints are not blocked — they surface dunning_suspended: true on the site instead.

Async Patterns

Tasks

Most provisioning operations are async and answer 202 Accepted — but there is no single envelope. Do not assume a task reference; several 202 bodies carry no task id at all, and some carry nothing. The shapes actually in use:

That table is the complete set — no other /api endpoint answers 202.

Async operations include: PHP version change, backup creation, restore, restart, domain add/remove, account-role removal, cache enable/disable/purge, account delete. (Site creation, site resize/plan-change, domain orders, cPanel account orders and resizes, and Mailspace purchases and resizes are also async but are polled via the cart, not a task — see Carts below.)

Polling task status:

GET /api/tasks/:id
GET /api/sites/:site_id/tasks/:id

Task statuses:

Completion callback — attach a callback to an order (POST /api/orders, POST /api/orders/domain, or POST /api/cpanel_accounts) and CloudPress POSTs to your URL when that order's task finishes, instead of you polling:

{ "callback": { "url": "https://your-app.com/webhook", "authorization": "Bearer your-secret" } }

• Permitted keys: url (required) and authorization (optional, sent verbatim as the Authorization header). Any other key in the callback object is discarded. Only the three order-placing endpoints above consume a callback, so callbacks attach to order tasks only — it is ignored if sent anywhere else (a Mailspace purchase, for instance, does not accept one).
• What CloudPress sends: POST to your url with body { "timestamp": <epoch int>, "success": <bool>, "data": <task.data string> } and headers Authorization (verbatim) + Accept: application/json. Same outbound delivery layer as billing webhooks — 30s timeout, any 2xx counts as success. Retry backoff: the wait is chosen from the age of the delivery's timestamp (5 / 10 / 15 minutes), which in practice means the first retry lands ~5 minutes after the failed attempt and every retry after that at 15-minute intervals. Retries stop once that timestamp is more than 4 hours old, so delivery is at-least-once — de-dup on timestamp, which stays fixed across all retries of one delivery.
• When it fires: only on a terminal task transition — the task reaching OK, FAILED, or CANCELLED (including when an infrastructure component reports the result in via POST /api/webhooks/task/:id, which sets OK or FAILED). Intermediate transitions such as PENDING → RUNNING, or a pause, queue no delivery. So expect one callback per order task, not a status stream.
• Mechanism: the callback is stashed on the cart and stamped onto the order task, and the delivery is queued at that terminal transition if the task carries one.
• Utility endpoints (distinct from your receiver — these are inbound to CloudPress): GET /api/webhooks/task returns {ip_address} for a reachability test; POST /api/webhooks/task/:id is how a task result is reported into CloudPress (used by infra; API-key credential, OAuth-blocked; idempotent via a data+success digest), and posting that result is what triggers the outbound callback. It expects an account context and, unlike the endpoints listed under X-Auth-Account, does not check for one — sending it without one produces a 500, not a 400.

Carts (order/billing async window)

Five endpoints return the same cart envelope (status accepted): POST /api/orders; site plan-change (PATCH /api/sites/:id with plan); cPanel account order/resize (POST/PATCH /api/cpanel_accounts); Mailspace purchase/resize (POST/PATCH /api/mailspace); and the paid registrant change (POST /api/domain_registrations/:id/registrant_change). Poll the cart for materialized orders. orders is empty during the async window on Stripe-billed plans, and a declined off-session charge is still a 202 — never branch on the HTTP status. What to branch on depends on the operation: a purchase reports a declined or challenged charge as payment.status: "awaiting_authentication", but a resize (site plan-change, cPanel resize, Mailspace resize) builds a proration cart and reports processing with a populated payment.hosted_invoice_url instead. On a resize, branch on that URL being non-null. See Orders and Carts.

Registrar processes

Domain-registration mutations may complete synchronously (200) or open a registrar process (202 with pending_process). Poll via the processes endpoints. A registration with an in-flight process is "busy" and rejects further mutations with 409 registration_busy.

Feature & Plan Gating

• domain-registration feature flag — when off, all domain-registration and domain-contact endpoints return 503 {"errors":[...],"code":"feature_disabled"}.
• Shield plan entitlement — the site's product must include Shield, else 403 {"error":"shield_not_in_plan"}. The gate is declared on this enumerated set: /api/sites/:id/shield (show/create/update/destroy) plus the nested shield/events, shield/bot_detection, shield/waf, shield/waf_custom_rules, shield/rate_limits and shield/access_lists — reads as well as writes. Two of those actions additionally require a premium plan — PATCH /api/sites/:id/shield/bot_detection and POST /api/sites/:id/shield/waf_custom_rules — else 403 {"error":"shield_premium_required"}.
• Bunny activation — CDN/Shield endpoints return 409 cdn_not_active / shield_not_active when the underlying Bunny pull zone / shield zone hasn't been provisioned yet.
• Registrar availability — registrar operations on a TLD with no configured registrar return 503 registrar_unavailable.
• cPanel availability — cPanel hosting is limited to workspaces that are already cPanel customers; every /api/cpanel_accounts route returns 403 {"errors":[...],"code":"cpanel_not_enabled"} for any other workspace. A 503 cpanel_unavailable means the hosting platform could not be reached and is retryable; cpanel_not_enabled is not.
• Mail platform availability — when mail hosting is not configured, every /api/mailspace/:id/… endpoint returns 503 {"errors":["The mail server is not configured."],"code":"stalwart_unavailable"}. Reads included — this gate runs before the mailspace is even looked up, so it is not a write-only refusal.
• Mailspace state gates — the endpoints nested under /api/mailspace/:id apply four further gates in this order, and a client should map each code to exactly one cause: 403 not_authorized (no edit permission on the mailspace's own workspace), 403 mailspace_suspended (staff block or dunning hold), 403 pending_delete (mailspace soft-deleted), 409 not_provisioned (mailspace not yet in the mail platform — complete domain verification first). Two of those four are decided on the HTTP verb, not the action name — not_authorized and pending_delete: GET and HEAD always pass, so reads stay available on a soft-deleted mailspace for its whole retention window. mailspace_suspended is not verb-gated: a staff-blocked or dunning-held mailspace refuses reads as well as writes, even though its message reads "cannot be modified". Do not infer the verb rule from one code to the next. Two deliberate exceptions: the mailspace purge endpoint does not apply pending_delete (being soft-deleted is its precondition), and the primary-domain verification endpoint does not apply not_provisioned (it runs before provisioning is possible).
• Mailspace read failures are 503 with a per-resource code, and an empty collection is never one of them. Every index inside a mailspace reads the mail server live, and each answers its own code when that read could not be performed — mailboxes_unavailable, domains_unavailable, aliases_unavailable, groups_unavailable, mailing_lists_unavailable, archived_items_unavailable, purged_mailboxes_unavailable. The code names which read failed, which is the point: GET .../groups has two, and group_members_unavailable now means only that the member tally failed while the group list itself came back. So an empty array in a 200 means the mail server was asked — a 200 no longer hides a failed read, and a client may reconcile its own state against it. That buys honesty about the read, not completeness: every one of these lists is capped upstream (500 rows) and truncates silently, with no total and no flag, and purged_mailboxes has the worst of it — its cap is applied server-wide before tenant filtering, so an empty 200 there is still not proof the mail is gone. Three further exceptions, none of which generalises: mailbox mail rules answer 422 mail_rules_unavailable rather than a 503; the app-password list, the masked-email list, the delivery logs and the by-id group and mailing-list lookups are still tolerant and degrade to an empty result or a 404.
• On a mailspace write, 503 answers one of two opposite questions — check which. The distinction is deliberate and it is per code, not per status: some 503s mean nothing was attempted, others mean something was attempted and the outcome is unknown. restore_unavailable (purged-mailbox restore) and archived_item_lookup_unavailable mean nothing happened and the resource is untouched. `restore_un

…(truncated)