cPanel accounts

Accountscope vereist; voeg de header X-Auth-Account toe met je Account-ID. Reads vereisen de OAuth-scope cpanel:read. Elke write op deze pagina is niet beschikbaar via OAuth: bij bestellen, resizen en opzeggen is geld gemoeid, en het wachtwoord wijzigen, opruimen, domeinen beheren en een sessie openen geven elk de controle over de hosting zelf uit handen. Ze declareren allemaal geen scope en zijn fail-closed op 403 endpoint not available via OAuth voor elk OAuth-token, welke scopes het ook draagt — dezelfde behandeling die POST /api/orders en registrant_change krijgen. Gebruik daarvoor een sessie- of API-sleutel-credential. Zie OAuth en Authenticatie.

Beschikbaarheid wordt per workspace ingeschakeld

cPanel hosting is niet beschikbaar op elke workspace. Het wordt ingeschakeld voor workspaces die al cPanel-klant zijn — een workspace die dat niet is, geeft 403 cpanel_not_enabled terug op elk endpoint op deze pagina, ook op de read-endpoints.

Reads combineren de account-mirror van het hostingplatform met het lokale record dat CloudPress per account bijhoudt, zodat een waarde een paar minuten kan achterlopen op WHM (zie local_package hieronder). Writes lopen via dezelfde cart- en checkoutmachinerie die het dashboard gebruikt, zodat er precies één pad is voor provisioning, prijsbepaling en facturatie — en net als de andere betaalde endpoints geven ze 202 Accepted terug met de gedeelde cart-polling-envelop in plaats van een afgerond resultaat. Zie Asynchrone bewerkingen.

Aangesproken via de gebruikersnaam, niet via een GUID

Anders dan de rest van deze API wordt een cPanel account geïdentificeerd door zijn cPanel-gebruikersnaam — GET /api/cpanel_accounts/acmeco01, niet een GUID. Het padsegment is beperkt tot de WHM-tekenset voor gebruikersnamen (letters, cijfers en underscores); iets anders bereikt de lookup niet.

Verzoekbewakingen

Worden in deze volgorde toegepast, vóór de actie draait. De eerste die faalt, beantwoordt het verzoek.

Geldt voor	Voorwaarde	Reactie
alle	`X-Auth-Account` ontbreekt of is niet te herleiden	`400` `missing_account`
alle	cPanel hosting is niet geconfigureerd op het platform	`503` `cpanel_unavailable`
alle	workspace is geen cPanel-klant	`403` `cpanel_not_enabled`
create, update, destroy	credential heeft geen gebruiker (een system Account-bearer API key)	`401` `user_required`
create, update	workspace zit in een trial	`403` `trial_account`
show, update, destroy	gebruikersnaam onbekend, of niet van jou	`404` `account_not_found`
show, update, destroy	de account-mirror kon tijdens de lookup niet worden gelezen	`503` `cpanel_unavailable`
create, update	gebruiker mag geen facturatie beheren op de workspace die eigenaar is	`403` `not_authorized`
destroy	gebruiker mag de service-lifecycle niet beheren op de workspace die eigenaar is	`403` `not_authorized`
update	account wordt verwijderd	`403` `pending_deletion`
update	account is geblokkeerd door een medewerker	`403` `account_suspended`
update	account is geblokkeerd vanwege een onbetaalde factuur	`402` `service_suspended`

Waarom een ontbrekende header een 400 is en geen 403

De accountscope-controle draait bewust vóór de beschikbaarheidsbewaking, zodat een verzoek dat simpelweg X-Auth-Account is vergeten de standaard 400 missing_account krijgt in plaats van cpanel_not_enabled — wat zou lezen als "je workspace kan geen cPanel afnemen", terwijl het echte probleem de header is.

Rolcontroles gelden op de workspace die eigenaar is

Toegang kan direct aan een gebruiker worden gegeven, dus het account dat je aanspreekt is niet altijd eigendom van de workspace in X-Auth-Account. Facturatie- en lifecycle-rollen worden daarom gecontroleerd op de workspace die eigenaar is van het account, en een resize verrekent het abonnement van die workspace pro rata. Facturatiebeheerder zijn in de ene workspace geeft je niet het recht om het account van een andere te resizen.

Een gebruikersnaam waarvoor je geen rechten hebt, geeft 404 account_not_found terug en geen 403 — de API bevestigt niet dat een gebruikersnaam elders op het platform bestaat. De drie toestandsbewakingen op update draaien in de hierboven getoonde volgorde, zodat je bij meerdere tegelijk het meest bruikbare antwoord krijgt: eerst herstellen, dan contact opnemen met support, dan de factuur betalen. De body van pending_deletion bevat ook delete_scheduled_at.

show is bewust niet aan een toestand gebonden: een geblokkeerd account of een account dat wordt verwijderd, kan nog steeds worden opgevraagd.

Endpoints per account

De endpoints voor het wachtwoord, opruimen, domeinen en de sessie hangen onder één account, dus ze draaien allemaal dezelfde eerste vier bewakingen — missing_account, cpanel_unavailable, cpanel_not_enabled, en daarna de lookup en de tenancy-controle die 404 account_not_found beantwoorden. Daarbovenop:

Endpoint	Gebruiker nodig	Trial	Rol op de workspace die eigenaar is	Vergrendeld tijdens verwijdering
`GET …/domains`	nee	toegestaan	geen	nee
`POST …/domains`	ja	geweigerd	facturatie beheren	ja
`DELETE …/domains/{domain}`	ja	geweigerd	facturatie beheren	ja
`PATCH …/password`	ja	geweigerd	facturatie beheren	ja
`POST …/purge`	ja	geweigerd	service-lifecycle	n.v.t. — het vereist dat het account wordt verwijderd
`POST …/session`	ja	geweigerd	bewerken	nee

"Gebruiker nodig" betekent dat een system Account-bearer API key wordt geweigerd met 401 user_required; een trial-workspace krijgt 403 trial_account; een mislukte rolcontrole krijgt 403 not_authorized.

Anders dan PATCH /api/cpanel_accounts/{username} dragen deze endpoints geen blokkeringsbewakingen — er is bij geen van alle een account_suspended- of service_suspended-antwoord.

Waarom de domeinlijst de ruimste van de zes is

GET …/domains vereist geen gebruiker en geen rol, omdat Een cPanel account bekijken dat ook niet doet. De domeinlijst van een account moeilijker leesbaar maken dan het account waar hij bij hoort, zou een asymmetrie zijn zonder iets erachter.

Een account dat wordt verwijderd, is vergrendeld

Het wachtwoord wijzigen of een domein toevoegen of verwijderen op een account dat is ingepland voor verwijdering, geeft 403 pending_deletion terug, met delete_scheduled_at in de body. Herstel het account eerst — en dat is een dashboardactie (zie Nog steeds alleen in het dashboard), dus een onbewaakte job kan hier beter op alarmeren dan het opnieuw te proberen.

Een opgezegd account is ook op de hostingserver geblokkeerd, dus reken er niet op dat je er nog bij de inhoud kunt — herstel het eerst.

Er is geen step-up-authenticatie in de API

Het dashboard laat je je identiteit opnieuw bevestigen vóór een wachtwoordwijziging, een opruimactie of het verwijderen van een domein. De API heeft geen vergelijkbare prompt, dus een first-class credential — sessie of API-sleutel, nooit OAuth — plus de rolcontrole hierboven komt daarvoor in de plaats. Dezelfde vervanging maken DELETE /api/cpanel_accounts/{username}, DELETE /api/sites/{id} en GET /api/domain_registrations/{id}/epp_code al.

cPanel accounts opvragen

GET /api/cpanel_accounts

Params (optioneel)

page: Integer | paginanummer (standaard: 1)
per_page: Integer | records per pagina (standaard: 50, max: 100)
q: String | case-insensitive zoeken op deelstring in gebruikersnaam, serverhostnaam, primair domein en add-on-/aliasdomeinen

Teruggegeven params

cpanel_accounts: Array
- username: String
- primary_domain: String | null wanneer voor het account nog geen hoofddomein is vastgelegd
- package: Object | het live WHM-pakket
  - code: String | de live WHM-pakketcode, in hoofdletters. Meestal S, M, L of XL, maar niet beperkt tot die waarden — wat WHM rapporteert wordt ongefilterd doorgegeven, dus legacy-codes en codes buiten de catalogus verschijnen hier letterlijk. null wanneer WHM geen pakket rapporteert
  - key: String | mini, basic, pro, max; null voor een pakket dat niet in de huidige catalogus staat
  - label: String | bijv. Pro; valt terug op de ruwe code
- local_package: String | WHM-code. Alleen aanwezig zolang het pakket dat CloudPress het laatst heeft voorzien afwijkt van de live mirror — dus wanneer WHM een create of resize heeft toegepast maar de mirror nog niet is gesynchroniseerd. De rest van de tijd weggelaten
- disk: Object
  - used_mb: Integer
  - quota_mb: Integer
- server: String | genormaliseerde hostnaam, of null
- mailbox_count: Integer
- addon_domain_count: Integer
- state: String | active, provisioning, dunning_suspended, admin_suspended, pending_deletion
- delete_scheduled_at: DateTime | null tenzij het account is ingepland voor verwijdering
- subscription: Object | null wanneer het account geen lokaal abonnement heeft
  - id: String | abonnements-GUID
  - status: String
  - term: String | de huidige termijn van het abonnement
- account: Object | de workspace die eigenaar is. Weggelaten wanneer het account geen lokaal record heeft (een toekenning op klantniveau)
  - id: String
  - name: String

state en het provisioningvenster

state is afgeleid, en pending_deletion gaat vóór beide blokkeringsvlaggen — het is de eindtoestand en de enige die verandert welke bewerkingen mogelijk zijn. Een net besteld account staat op provisioning totdat WHM het aanmaken heeft afgerond; die rijen worden opgebouwd uit het lokale record, dus disk.used_mb / disk.quota_mb en server zijn null, mailbox_count en addon_domain_count zijn 0, local_package is nooit aanwezig, en package geeft het bestelde pakket weer in plaats van een live meting.

Plafond van 500 accounts

Er zijn in totaal maximaal 500 accounts bereikbaar, hoe je ook pagineert. De accountlookup van de workspace is afgetopt op 500 en pagina's worden uit die afgetopte set genomen, dus een workspace met meer dan 500 cPanel accounts kan de rest niet bereiken via dit endpoint — verdere pagina's raken simpelweg op. Beperk het resultaat met q in plaats van dieper te pagineren. (De lijst in het dashboard valt onder hetzelfde plafond.)

De reactie bevat geen metadata met een totaalaantal; pagineer door totdat cpanel_accounts leeg terugkomt, met inachtneming van het plafond hierboven.

Wat niet wordt getoond

Alleen cPanel hosting-accounts verschijnen. Alleen-mail-accounts worden uitgesloten: het zijn geen cPanel hostingaccounts, en show / update / destroy geven er alle drie 404 voor terug, dus ze tonen zou gebruikersnamen adverteren die niets anders op deze pagina kan aanspreken. Accounts waarvan het lokale record al is opgeruimd worden ook uitgesloten, ook als de mirror ze nog teruggeeft.

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
503 cpanel_unavailable | de account-mirror kon niet worden gelezen

Dit endpoint faalt expliciet

Wanneer de mirror onbereikbaar is, valt het dashboard terug op een banner en rendert het de pagina alsnog. De API doet het tegenovergestelde en meldt de fout expliciet als 503 cpanel_unavailable, zodat een client een storing nooit aanziet voor "je hebt geen cPanel accounts". Probeer het opnieuw in plaats van je gegevens af te stemmen op een lege lijst.

Een cPanel account bekijken

GET /api/cpanel_accounts/:username

Geeft hetzelfde object terug als de lijst, onder een cpanel_account-key.

Teruggegeven params

cpanel_account: Object | zie cPanel accounts opvragen

Aantallen en het primaire domein worden uit de gecachte mirror gelezen en degraderen in plaats van te falen: als een waarde niet gelezen kan worden, komt mailbox_count terug als 0 en valt primary_domain terug op het lokaal vastgelegde domein.

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
503 cpanel_unavailable | de account-mirror kon niet worden gelezen

Een cPanel account bestellen

POST /api/cpanel_accounts

Hier wordt direct afgerekend

cPanel hosting werkt op basis van vooruitbetaling. Dit endpoint belast de standaard opgeslagen betaalmethode van het facturatieaccount off-session en voorziet asynchroon. Er is geen synchrone succestak en geen checkout-redirect — het geeft altijd 202 Accepted terug. Het WHM-account (gebruikersnaam en een gegenereerd wachtwoord) wordt aangemaakt zodra de betaling is afgewikkeld.

Vereist een user-scoped credential; een system Account-bearer API key geeft 401 user_required terug. Trial-workspaces geven 403 trial_account terug. Niet beschikbaar via OAuth.

Params

package: String (required) | pakket-key (mini, basic, pro, max) of WHM-code (S, M, L, XL)
term: String (optional) | monthly of annual; standaard de facturatietermijn van de workspace
domain: String (optional) | een domein dat de workspace al bezit, gebruikt als hoofddomein van het account. Laat je het weg, dan genereert cPanel een placeholder-domein
callback: Object (optional) | uitgaande melding wanneer het asynchrone werk klaar is — hetzelfde contract als POST /api/orders, zie Callbacks
- authorization: String | volledige waarde van de Authorization-header. Voorbeeld: Bearer 12345
- url: String | volledig gekwalificeerde URL

Een nieuw domein registreren is een aparte bestelling

domain moet al een domein in de workspace zijn en daadwerkelijk geregistreerd — een naam die alleen aan een site is gekoppeld, is niet genoeg. Een domein registreren in dezelfde cart wordt hier niet ondersteund; doe eerst POST /api/orders/domain en bestel daarna het hostingaccount.

curl -X POST https://my.cloudpress.com/api/cpanel_accounts \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"package": "pro", "term": "monthly", "domain": "acmeco.com"}'

Teruggegeven params (altijd 202 Accepted)

status: String | "accepted"
cart: Object
- token: String
- status: String | de status van de winkelwagen zelf. Meestal active, processing of checked_out; terwijl je pollt kan die ook awaiting_provisioning worden (betaling geïnd, provisioning geparkeerd) of expired (de winkelwagen is mislukt of verlaten), dus behandel de lijst als voorbeelden en niet als een gesloten set
- rollup_status: String
- poll_url: String | absolute URL, bijv. https://your-instance/api/carts/<token>
payment: Object
- status: String | processing, succeeded, awaiting_authentication
- method_type: String | het opgeloste Stripe-betaalmethodetype. Meestal card of sepa_debit, maar elk Stripe-type kan hier terechtkomen — us_bank_account, bacs_debit, acss_debit, au_becs_debit, customer_balance, ideal en andere zijn allemaal mogelijk. null zolang het niet kan worden bepaald
- hosted_invoice_url: String | null
orders: Array | elk { id, status, poll_url }; leeg tijdens het asynchrone venster

Poll cart.poll_url om de bestelling te ontdekken, en daarna elke orders[].poll_url totdat de status een eindwaarde heeft. orders is in het begin leeg op Stripe-facturatieplannen — de bestelling wordt aangemaakt nadat de belasting is afgewikkeld. Betaalscenario's (3DS-parkering, SEPA, creditsaldo, weigering) gedragen zich exact zoals gedocumenteerd bij PATCH /api/sites/:id.

Fouten

Autorisatie / gating:

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 trial_account | trial-workspaces kunnen geen cPanel hosting afnemen
403 not_authorized | gebruiker mag geen facturatie beheren op deze workspace

Validatie (400, geen belasting, geen bestelling aangemaakt):

unknown_package | package is geen bekende pakket-key of WHM-code
invalid_term | term is niet monthly of annual
product_unavailable | het gevraagde pakket wordt niet aangeboden op dit facturatieplan
no_default_payment_method | het facturatieaccount is niet klaar om te belasten

Verwerking (422):

no_price_for_plan | geen prijs voor het gevraagde pakket en de gevraagde termijn
domain_not_owned | domain is geen domein in deze workspace
domain_not_registered | domain is nergens geregistreerd
domain_in_use | domain is al in gebruik op een ander hostingaccount
cart_add_failed | de cart weigerde het item
cart_pay_failed | de off-session-belasting kon niet worden gestart
503 cpanel_unavailable | cPanel is niet geconfigureerd, of domain kon niet worden gecontroleerd tegen de hostingservers

Pakket wijzigen (resize)

PATCH /api/cpanel_accounts/:username

Wijzigt het WHM-pakket en verrekent de facturatie opnieuw pro rata. Op een Stripe-facturatieplan is dit een pro-rata-cart die off-session wordt belast — dezelfde machinerie als een resize van een WordPress-site; op een niet-Stripe-plan bouwt het een resize-bestelling die de pakketwijziging zonder betaling toepast. Geeft 202 Accepted terug met dezelfde cart-envelop als Een cPanel account bestellen.

De termijn verandert nooit

Een resize wordt altijd geprijsd op de huidige termijn van het actieve abonnement. Er is hier geen term-, domain- of callback-param, dus dit endpoint geeft nooit invalid_term, domain_not_owned of domain_in_use terug.

Params

package: String (required) | doel-pakket-key (mini, basic, pro, max) of WHM-code (S, M, L, XL)

Teruggegeven params (altijd 202 Accepted)

Identieke envelop als Een cPanel account bestellen:

status: String | "accepted"
cart: Object | { token, status, rollup_status, poll_url }
payment: Object | { status, method_type, hosted_invoice_url }
orders: Array | [{ id, status, poll_url }] (leeg tijdens het asynchrone venster)

Probeer een resize niet blind opnieuw

Een pakketwijziging wordt geclaimd voordat er geld beweegt, dus een tweede PATCH die wordt verstuurd terwijl de eerste nog wordt toegepast, wordt geweigerd met 409 resize_in_flight in plaats van een tweede pro rata te belasten. "Zit al op dat pakket" wordt gecontroleerd tegen zowel de live mirror als het laatst voorziene pakket, wat hetzelfde venster van de andere kant dichtzet. Als een verzoek een time-out geeft, poll dan de cart of vraag het account opnieuw op in plaats van de PATCH opnieuw te versturen.

Downgrades moeten binnen het huidige gebruik passen

Een kleiner pakket wordt geweigerd met 422 usage_exceeds_package wanneer het huidige schijf-, mailbox- of add-on-domeingebruik van het account meer is dan het doelpakket bevat — WHM zou anders de kleinere quota alsnog toepassen en het account direct boven quota achterlaten. Verlaag eerst het gebruik. Upgrades worden nooit op gebruik gecontroleerd, dus een account dat op een ouder pakket boven de huidige limieten zit, kan altijd omhoog.

Fouten

Autorisatie / gating:

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 trial_account | trial-workspaces kunnen niet resizen
403 not_authorized | gebruiker mag geen facturatie beheren op de workspace die eigenaar is
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential

Accounttoestand:

403 pending_deletion | het account wordt verwijderd en is vergrendeld — herstel het eerst (de body bevat delete_scheduled_at)
403 account_suspended | geblokkeerd door een medewerker; neem contact op met support
402 service_suspended | geblokkeerd vanwege een onbetaalde factuur

Validatie (400):

unknown_package | package is geen bekende pakket-key of WHM-code
product_unavailable | het doelpakket wordt niet aangeboden op dit facturatieplan
no_default_payment_method | er is een opgeslagen standaardbetaalmethode nodig om de proratie off-session te belasten, en die is niet gevonden

Conflict (409):

resize_in_flight | een eerdere pakketwijziging wordt nog toegepast

Verwerking (422):

same_package | zit al op dat pakket
usage_exceeds_package | het doelpakket is kleiner dan het huidige schijf-, mailbox- of add-on-domeingebruik
no_price_for_plan | geen prijs voor het doelpakket op de termijn van het abonnement
no_billing_subscription | Stripe-facturatieplan zonder gekoppeld abonnement om pro rata tegen te verrekenen (een account dat is gemigreerd en hier nooit is gefactureerd)
subscription_not_proratable | de cart kon niet als pro-rata-wijziging worden klaargezet; geweigerd in plaats van belast als een volledig nieuwe aankoop
cart_add_failed | de cart weigerde het item
cart_pay_failed | de off-session-belasting kon niet worden gestart
503 cpanel_unavailable | cPanel is niet geconfigureerd, of de mirror kon niet worden gelezen

Een cPanel account opzeggen

DELETE /api/cpanel_accounts/:username

Dit is een soft delete. Het legt de bewaartermijn vast, zegt de facturatie op — waarmee verlengingen stoppen en de niet-gebruikte eerste termijn wordt gecrediteerd — en blokkeert het account op WHM. Het account blijft herstelbaar vanuit het CloudPress-dashboard tot delete_scheduled_at, waarna het definitief wordt verwijderd.

Vereist lidmaatschap van de service-lifecycle-rol op de workspace die eigenaar is. Medewerkers die geen lid zijn van de workspace zijn uitgesloten, en er is geen step-up-authenticatie in de API die in de plaats kan komen van de identiteitsbevestiging in het dashboard.

Geeft 202 Accepted terug.

Teruggegeven params

status: String | "pending_deletion"
username: String
delete_scheduled_at: DateTime | de vastgezette verwijderdatum; tot dat moment herstelbaar

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 not_authorized | gebruiker mag de service-lifecycle niet beheren op de workspace die eigenaar is
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
422 account_already_purged | de mirror toont het account nog, maar het is al opgeruimd
422 account_delete_failed | het account kon niet worden ingepland voor verwijdering
503 cpanel_unavailable | cPanel is niet geconfigureerd, of de servercredentials van het account konden niet worden bepaald

Een account direct opruimen

POST /api/cpanel_accounts/:username/purge

Permanent en onomkeerbaar. Geeft het account en zijn gegevens nu vrij in plaats van op delete_scheduled_at. Dit verkort alleen een bewaartermijn die opzeggen al heeft geopend — het account moet al op verwijderen wachten, en er is geen gecombineerd pad dat in één keer opzegt én opruimt, dus één verkeerde aanroep kan nooit een actief account vernietigen.

Geeft 202 Accepted terug. Het verwijderen zelf draait op de achtergrond, maar het account verdwijnt direct uit GET /api/cpanel_accounts — de afwezigheid in die lijst is het signaal waarop je moet pollen, en er is geen task om te volgen.

Vereist lidmaatschap van de service-lifecycle-rol op de workspace die eigenaar is, en is niet beschikbaar via OAuth.

Teruggegeven params

status: String | "purging"
username: String

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 trial_account | de workspace zit in een trial
403 not_authorized | gebruiker mag de service-lifecycle niet beheren op de workspace die eigenaar is
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
422 account_not_pending_deletion | het account is actief; zeg het eerst op
503 cpanel_unavailable | cPanel is niet geconfigureerd, of de mirror kon niet worden gelezen

Het cPanel-wachtwoord wijzigen

PATCH /api/cpanel_accounts/:username/password

Zet het wachtwoord direct op het hostingaccount — er is geen asynchroon venster, dus het oude wachtwoord werkt meteen niet meer.

Dit is geen noodstop voor sessies

Of cPanel ook sessies afbreekt die al openstonden onder het oude wachtwoord, is gedrag van cPanel zelf en wordt hier niet gegarandeerd. Roteer je omdat een credential is gelekt, beschouw deze aanroep dan niet als bewijs dat de gelekte sessie gesloten is.

De wachtwoordsterkte wordt afgedwongen door de hostingserver, niet door CloudPress; een waarde die hij weigert komt terug als password_change_failed. De fouttekst is bewust algemeen — het bericht van de server zelf wordt gelogd in plaats van doorgegeven.

Params

password: String (required) | het nieuwe wachtwoord. Er is geen password_confirmation — dat hoort bij het formulier, niet bij het API-contract

Teruggegeven params

status: String | "changed"
username: String

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 trial_account | de workspace zit in een trial
403 not_authorized | gebruiker mag geen facturatie beheren op de workspace die eigenaar is
403 pending_deletion | het account is ingepland voor verwijdering; herstel het eerst
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
422 password_blank | geen password meegestuurd
422 password_change_failed | de server weigerde de waarde, meestal op sterkte
503 cpanel_unavailable | cPanel is niet geconfigureerd, of de servercredentials van het account konden niet worden bepaald

Domeinen van een account opvragen

GET /api/cpanel_accounts/:username/domains

De aliassen, subdomeinen en add-on-domeinen die aan één account hangen. Wordt live van de hostingserver gelezen (met de lokale mirror als terugval), zodat een domein dat via deze API is toegevoegd verschijnt zodra de server klaar is met het opbouwen ervan.

Elke rij bevat twee typevelden. type is de ruwe waarde die de server rapporteert en is schema-afhankelijk — main, addon, sub, parked, alias en andere schrijfwijzen komen allemaal voor. domain_type is het genormaliseerde vocabulaire dat deze API spreekt, en dat is wat de rest van deze sectie bedoelt met de soort van een domein; het is null voor het hoofddomein van het account, dat niet verwijderd kan worden.

Teruggegeven params

domains: Array<Object>
- name: String
- type: String | het ruwe type dat de hostingserver rapporteert; null wanneer hij er geen rapporteert
- domain_type: String | parked, subdomain of addon; null voor het hoofddomein
usage: Object | tellers per soort en de limieten van het pakket
- addon: Object
  - count: Integer
  - limit: Integer | de numerieke limiet; null bij onbeperkt of onbekend
  - unlimited: Boolean | true alleen wanneer de server daadwerkelijk onbeperkt meldde
  - at_limit: Boolean | true alleen tegen een echte numerieke limiet, zodat een onbekende limiet nooit blokkeert
- alias: Object | dezelfde vorm als addon
- subdomain: Object | dezelfde vorm als addon

limit: null is bewust dubbelzinnig

Een limit van null betekent óf "onbeperkt", óf "we konden de limiet niet lezen" — unlimited is het veld dat die twee onderscheidt. Vertak op at_limit, dat alleen true is tegen een limiet die echt bekend is.

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
503 cpanel_unavailable | cPanel is niet geconfigureerd, of de domeinlijst kon niet worden gelezen

Een domein toevoegen

POST /api/cpanel_accounts/:username/domains

Welke parameters vereist zijn, hangt af van domain_type:

Parked (alias) en add-onSubdomein

Geef de volledige hostnaam mee in domain. Die moet al geregistreerd zijn en eigendom van deze workspace — een naam die dat niet is, krijgt het bewust algemene domain_not_eligible in plaats van uitleg over welke helft faalde, zodat je hiermee niet kunt aftasten hoe een domein op het platform bekend is.

Het doel dat een alias deelt is geen parameter; dat wordt serverzijdig altijd het primaire domein van het account.

Geef label (één enkel DNS-label, zonder punten) en rootdomain mee. Het bovenliggende domein moet een van de eigen domeinen van dit account zijn — het hoofddomein, de add-on-domeinen en de parked-/aliasdomeinen komen allemaal in aanmerking.

Geeft 202 Accepted terug en geen 201, en dat verschil doet ertoe: de hostingserver meldt succes voordat het opnieuw opbouwen van de vhost en de zone klaar is, dus het domein kan daarna nog even ontbreken in Domeinen van een account opvragen. Poll die lijst op de naam in plaats van de reactie te behandelen als bewijs dat het domein live is.

Params

domain_type: String (required) | parked, subdomain of addon
domain: String (required voor parked en addon) | de volledige hostnaam
label: String (required voor subdomain) | één enkel DNS-label, zonder punten
rootdomain: String (required voor subdomain) | het bovenliggende domein
dir: String (optional, subdomain en addon) | documentroot

Teruggegeven params

status: String | "accepted"
domain: String
domain_type: String

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 trial_account | de workspace zit in een trial
403 not_authorized | gebruiker mag geen facturatie beheren op de workspace die eigenaar is
403 pending_deletion | het account is ingepland voor verwijdering; herstel het eerst
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
422 invalid_domain_type | domain_type is niet een van de drie
422 domain_blank | geen domain meegestuurd
422 invalid_hostname | domain is geen geldige hostnaam
422 label_blank | geen label meegestuurd voor een subdomein
422 invalid_label | label is geen geldig DNS-label
422 rootdomain_blank | geen rootdomain meegestuurd voor een subdomein
422 invalid_parent_domain | het bovenliggende domein is niet een van de eigen domeinen van dit account
422 domain_not_eligible | het domein is niet geregistreerd op deze workspace, of kan hier niet worden toegevoegd
422 addon_domain_limit_reached | de add-on-limiet van het pakket is bereikt
422 alias_domain_limit_reached | de aliaslimiet van het pakket is bereikt
422 domain_create_failed | de hostingserver weigerde de wijziging
503 cpanel_unavailable | cPanel is niet geconfigureerd, of de server was niet bereikbaar

Een domein verwijderen

DELETE /api/cpanel_accounts/:username/domains/:domain

:domain is de naam van het domein, geen ID. Het moet een van de eigen domeinen van dit account zijn; al het andere krijgt 404 domain_not_found — hetzelfde antwoord dat een volstrekt onbekende naam krijgt, zodat je hiermee niet kunt aftasten wat er elders op het platform staat.

De soort verwijdering wordt serverzijdig afgeleid uit de eigen rij van het domein in de lijst. Er is geen domain_type-parameter, en meesturen wordt genegeerd. Het hoofddomein van het account kan niet worden verwijderd (invalid_domain_type) — zeg in dat geval het account op.

DNS wordt alleen opgeruimd bij subdomeinen

Een subdomein verwijderen haalt ook de records ervan uit de bovenliggende zone. Bij een alias of een add-on-domein blijft de zone bewust staan, zodat het domein opnieuw gebruikt kan worden.

Params (optioneel)

rootdomain: String | een hint voor het bovenliggende domein van een subdomein. Wordt alleen gehonoreerd wanneer het echt een van de bovenliggende domeinen van dit account is; anders wint de serverzijdige afleiding

Teruggegeven params

status: String | "removed"
domain: String
domain_type: String

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 trial_account | de workspace zit in een trial
403 not_authorized | gebruiker mag geen facturatie beheren op de workspace die eigenaar is
403 pending_deletion | het account is ingepland voor verwijdering; herstel het eerst
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
404 domain_not_found | het domein hoort niet bij dit account
422 invalid_domain_type | het domein is het hoofddomein van het account, of de soort kon niet worden afgeleid
422 domain_remove_failed | de hostingserver weigerde de wijziging
503 cpanel_unavailable | cPanel is niet geconfigureerd, of de server was niet bereikbaar

Een cPanel-sessie openen

POST /api/cpanel_accounts/:username/session

Maakt een eenmalige, kortlevende inlog-URL aan voor de cPanel-interface van het account. Net als POST /api/sites/{id}/sso geeft het de URL terug en stuurt het nooit door, zodat geen enkele reactie van deze API ooit een cross-host 302 is en de aanroeper zelf bepaalt wat ermee gebeurt.

Behandel de URL als een credential

Wie hem heeft, is ingelogd als het cPanel-account. Log hem niet, cache hem niet en zet hem niet in een URL die ergens wordt vastgelegd.

De teruggegeven URL wordt gecontroleerd op dezelfde hostingserver waaraan het verzoek is gericht. Een URL die daar niet op staat, wordt geweigerd met sso_url_rejected en nooit teruggegeven, zodat een verkeerd geconfigureerde of gecompromitteerde server hier geen open redirect van kan maken.

Vereist bewerkrechten op de workspace die eigenaar is — leden met alleen leesrechten kunnen geen sessie openen.

Teruggegeven params

url: String | de eenmalige inlog-URL

Fouten

400 missing_account | geen workspace herleid uit X-Auth-Account
401 user_required | system Account-bearer key (geen gebruiker)
403 cpanel_not_enabled | cPanel hosting is niet ingeschakeld voor deze workspace
403 trial_account | de workspace zit in een trial
403 not_authorized | gebruiker mag de workspace die eigenaar is niet bewerken
404 account_not_found | onbekende gebruikersnaam, of niet toegankelijk voor deze credential
422 sso_url_rejected | de hostingserver gaf een inlog-URL terug die niet te vertrouwen was
503 cpanel_unavailable | de server was niet bereikbaar, of er kon geen sessie worden aangemaakt

Nog steeds alleen in het dashboard

Eén ding op de pagina cPanel accounts heeft geen API-route: een account herstellen dat wordt verwijderd. Opzeggen en opruimen zijn allebei te scripten; een opzegging terugdraaien niet.

Dat is minder een omissie dan het lijkt. Een account opzeggen zegt het abonnement volledig op en crediteert de ongebruikte termijn, dus herstel is een nieuwe aankoop — er wordt een winkelwagen voor het pakket opgebouwd en een betaling afgerond, waarna het bestaande hostingaccount weer wordt geactiveerd in plaats van opnieuw aangemaakt. Het is een checkout-flow, geen enkele aanroep.

Dat laat een echte asymmetrie achter waar je omheen moet plannen. Opzeggen en opruimen zijn allebei te scripten, opruimen is onomkeerbaar, en om een van beide terug te draaien is een mens bij een checkout nodig. Er is geen geautomatiseerde nooduitgang, dus een onbewaakte opruimjob moet elke opzegging die hij uitvoert als definitief behandelen.

Nodig via de API?

Laat het ons weten wat je automatiseert — aan een concrete workflow hebben we meer dan aan een algemeen verzoek om pariteit.