API-overzicht

Authenticatie

Alle /api/*-verzoeken authenticeren met een HTTP-token in de Authorization- header. Zowel het Token- als het Bearer-schema wordt geaccepteerd:

Authorization: Token {{ CloudPress API Token }}

Authorization: Bearer {{ CloudPress API Token }}

Er zijn drie soorten credentials, die allemaal op dezelfde manier worden aangeboden. De server bepaalt om welk type het gaat (eerst sessie / API-sleutel, daarna OAuth):

IP-beperking

Je kunt de toegang per IP beperken tot een specifieke API-sleutel in de CloudPress API Key Manager. Let op: wanneer je probeert verbinding te maken vanaf een niet-geautoriseerd IP, krijg je dezelfde reactie als wanneer je een ongeldige API-sleutel had opgegeven.

Standaard is er geen IP-beperking ingesteld.

Accountscope instellen

Sommige API-endpoints vereisen een accountscope. Om aan te geven onder welk account je wilt werken, voeg je de header X-Auth-Account toe met je Account-ID:

X-Auth-Account: {{ CloudPress Account ID }}

Gedrag:

• Voor een user API key scope't X-Auth-Account het verzoek naar één account en stelt het de accountcontext in. Zonder deze header geven list-endpoints resources terug over alle accounts waartoe de gebruiker van de sleutel toegang heeft.
• Twee lijsten negeren de header volledig. GET /api/domains en GET /api/dns_zones geven altijd elk domein / elke zone terug waar de gebruiker van de sleutel bij kan, of je X-Auth-Account nu meestuurt of niet. Filter aan de clientzijde als je de subset van één account nodig hebt.
• Sommige endpoints vereisen de header en geven 400 {"errors":["Missing X-Auth-Account"],"code":"missing_account"} terug wanneer hij ontbreekt — Orders, Carts, Subscriptions, Users, SSO, cPanel-accounts, en alle endpoints voor domeinregistratie. Het aanmaken van een DNS-zone hanteert dezelfde regel, maar rendert een eigen body zonder code-sleutel — 400 {"errors":["Missing X-Auth-Account"]} — vertrouw daar dus niet op missing_account. Mailspace create heeft ook een accountcontext nodig en antwoordt met 400 account_required.
• OAuth-tokens dragen altijd een account, dus voor die tokens wordt de header genegeerd.

Authenticatiefouten

Een mislukte authenticatie geeft 401 terug met de header WWW-Authenticate: Token realm="Application" en een lege body. Mogelijke oorzaken zijn: geen/ongeldig token, een IP dat niet op de toegangslijst van de sleutel staat, een trial-account, of een X-Auth-Account-waarde die niet overeenkomt met een account waartoe het token toegang heeft.

{ "error": "invalid_token", "error_description": "token audience is not valid for /api" }

Conventies

• Alle API-routes vallen onder /api/. Alle reacties zijn JSON.
• Resource-ID's zijn GUID's, behalve numerieke task-ID's, integer volume-ID's, integer DNS-recordtype-codes, en numerieke domain_contact-ID's.
• Tijdstempels zijn ISO 8601, UTC.
• Asynchrone bewerkingen geven 202 Accepted terug — poll een task, registrar-proces of cart om de voltooiing te controleren (zie Asynchrone bewerkingen).

Paginering

Paginering is geen conventie die overal geldt. Precies vijf index-endpoints accepteren page en per_page:

• GET /api/orders
• GET /api/subscriptions
• GET /api/domains
• GET /api/dns_zones
• GET /api/cpanel_accounts

Elke andere index-actie — sites, tasks, users, accounts, API-sleutels, DNS-records, domeinregistraties, domeincontacten, Mailspace, de domeinen van een cPanel account, en alle sub-resources van een site — negeert beide parameters en geeft de volledige set in één reactie terug.

Rate limiting

Verzoeken zijn beperkt tot 600 per 10 minuten, geteld per client-IP-adres en per controller — niet per credential. Daaruit volgen twee dingen:

• Eén credential krijgt een apart budget van 600 verzoeken tegen elke groep endpoints (sites, domeinen, DNS-zones, orders, …), dus werk dat over meerdere resources verdeeld is, valt niet onder één gedeeld maximum van 600.
• Twee credentials die vanaf hetzelfde bron-IP verzoeken sturen — achter één NAT of egress-gateway — delen één bucket en kunnen elkaars budget opmaken.

Bij overschrijding van de limiet wordt 429 met een lege body teruggegeven.

Foutreacties

{
  "errors": ["This site is pending deletion and is locked. Restore it to make changes."],
  "code": "pending_delete",
  "delete_scheduled_at": "2026-09-01T14:22:05Z"
}

Asynchrone bewerkingen

De meeste provisioning-bewerkingen zijn asynchroon en geven 202 Accepted terug met een referentie om te pollen.

• Tasks — verschillende bewerkingen openen een Task, maar niet alle geven het id terug. Drie gevallen, en het verschil telt zodra je je polling inricht:

  • 202 met een task_id — PHP-versiewijziging (PATCH /api/sites/{site-id}/variants/php) en cache inschakelen / uitschakelen / legen. Poll het teruggegeven id direct.
  • 202 zonder task-id — herstarten, een back-up maken en verwijderen, een restore, en een site-domein promoveren / verwijderen. Er wordt een Task aangemaakt, maar de responsbody is leeg; zoek hem dus op via GET /api/sites/{site-id}/tasks. Een site-domein toevoegen geeft wel een id terug, maar dat is de guid van het nieuwe domein, geen task-id.
  • Helemaal geen Task — het verwijderen van een accountrol (DELETE /api/accounts/{account-id}/roles/{id}) en accountverwijdering (DELETE /api/accounts/{account-id}) antwoorden met een kale 202. Er wordt niets aangemaakt om te pollen; lees het account of zijn rollen opnieuw uit om het resultaat te bevestigen.

  Poll een task met GET /api/tasks/:id of GET /api/sites/:site_id/tasks/:id. Taskstatussen: PENDING, RUNNING, OK, FAILED, CANCELLED, PAUSED. - Carts — site-aanmaak (POST /api/orders), site-resize / planwijziging (PATCH /api/sites/:id met plan), en domeinorders (POST /api/orders/domain) worden gepolld via de cart, niet via een task: ze geven een cart-envelop terug; poll de cart op gematerialiseerde orders. - Registrar-processen — mutaties voor domeinregistratie kunnen een proces openen; poll het op voltooiing.

Afrondingscallback

Bij het aanmaken van een order kun je optioneel een callback meegeven, zodat je een webhook ontvangt wanneer het asynchrone werk klaar is in plaats van te pollen:

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

Zie Callbacks voor het volledige contract.

About-endpoint

CloudPress biedt een 'about'-endpoint dat informatie geeft over wie je bent ingelogd als, evenals informatie over beschikbare resources. Het accepteert elk geldig token, ongeacht de OAuth-scope.

GET /api/about

curl -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  https://your-instance/api/about