Ga naar inhoud

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 en geeft 403 endpoint not available via OAuth voor elk OAuth-token, welke scopes het ook draagt; gebruik een sessie- of API-sleutel-credential. Zie OAuth en Authenticatie.

Beschikbaarheid wordt per workspace ingeschakeld

Een workspace die geen cPanel-klant is, krijgt 403 cpanel_not_enabled op elk endpoint op deze pagina, reads inbegrepen.

Writes gebruiken dezelfde cart en checkout als het dashboard en geven 202 Accepted terug met de gedeelde cart-pollingenvelop in plaats van een afgerond resultaat. Zie Asynchrone bewerkingen. Reads kunnen een paar minuten achterlopen op het hostingplatform (zie local_package hieronder).

Een cPanel account wordt aangesproken met zijn cPanel-gebruikersnaam (letters, cijfers en underscores), niet met een GUID: GET /api/cpanel_accounts/acmeco01.

Verzoekbewakingen

Worden in deze volgorde toegepast. 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 het account kon nu niet worden opgezocht, of het account is unavailable (zie cPanel accounts opvragen) 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 het account is een alleen-mail-account 422 resize_not_supported
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
  • Rolcontroles draaien op de workspace die eigenaar is van het account, en dat is niet altijd de workspace in X-Auth-Account.
  • Een niet-geautoriseerde gebruikersnaam geeft 404 account_not_found, niet 403.
  • De body van pending_deletion bevat ook delete_scheduled_at.
  • show is niet statusgebonden: een geblokkeerd account of een account dat wordt verwijderd kan nog steeds worden gelezen.
  • Een alleen-mail-account (kind: "mail_only") kan worden opgevraagd, bekeken, opgezegd en opgeruimd. Resize geeft 422 resize_not_supported, en de endpoints voor wachtwoord, domeinen en sessie geven 404 account_not_found.

Endpoints per account

De endpoints voor het wachtwoord, opruimen, domeinen en de sessie draaien de eerste vier bewakingen hierboven (missing_account, cpanel_unavailable, cpanel_not_enabled, en daarna de lookup die 404 account_not_found geeft). 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
PATCH …/domains/{domain} 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 geeft 403 not_authorized. Deze endpoints geven geen account_suspended- of service_suspended-antwoord.

Een account dat wordt verwijderd is vergrendeld

Het wachtwoord wijzigen of een domein toevoegen of verwijderen op een account dat voor verwijdering is gepland, geeft 403 pending_deletion, met delete_scheduled_at in de body. Een account herstellen is een dashboardactie (zie Nog steeds alleen in het dashboard), dus een onbewaakte job moet hierop alarm slaan in plaats van opnieuw te proberen.

De API kent geen step-up-authenticatie. Wachtwoordwijzigingen, opruimacties en domeinverwijderingen vereisen een sessie- of API-sleutel-credential (nooit OAuth) plus de rol hierboven.

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
    • kind: String | hosting of mail_only. Een alleen-mail-account heeft package.code null en schijfwaarden 0. Weggelaten bij rijen met provisioning en unavailable
    • primary_domain: String | null wanneer voor het account nog geen hoofddomein is vastgelegd
    • package: Object | het huidige pakket van het account
      • code: String | de huidige pakketcode, in hoofdletters. Meestal S, M, L of XL, maar niet beperkt tot die waarden: andere codes verschijnen hier letterlijk. null wanneer het account geen pakket heeft
      • 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 | pakketcode. Alleen aanwezig zolang een create of resize nog wordt doorgevoerd en package het laatst ingestelde pakket nog niet volgt. 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, unavailable
    • 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 het klaar is; 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.

unavailable-accounts

Een unavailable-rij is een account van jou dat niet aan precies één account op het hostingplatform te koppelen is. De rij heeft dezelfde vorm als een provisioning-rij, telt niet mee als actief account, en elk endpoint per account geeft 503 cpanel_unavailable terug totdat support het oplost.

De reactie bevat geen metadata met een totaalaantal; pagineer door totdat cpanel_accounts leeg terugkomt.

Wat wordt getoond

Zowel hosting- als alleen-mail-accounts verschijnen; onderscheid ze met kind. Accounts waarvan het lokale record al is opgeruimd worden niet getoond, ook als het platform ze nog vermeldt.

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 accountlijst kon niet worden gelezen; probeer het opnieuw

Dit endpoint faalt expliciet

Kan de accountlijst niet worden gelezen, dan meldt de API 503 cpanel_unavailable in plaats van een lege lijst, 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

Kan een aantal of het primaire domein niet worden gelezen, dan slaagt het verzoek toch: mailbox_count komt 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 accountlijst kon niet worden gelezen; probeer het opnieuw

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 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 pakketcode (S, M, L, XL)
  • term: String (optional) | monthly of annual; standaard de facturatietermijn van de workspace
  • domain: String (optional) | een bestaand domein, bij ons of elders geregistreerd, gebruikt als hoofddomein van het account. Laat je het weg, dan krijgt het account een tijdelijk domein; zolang je het hoofddomein niet in het dashboard hebt ingesteld, geeft het toevoegen van domeinen main_domain_temporary
  • 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; awaiting_bank_transfer of failed bij een bestelling per bankoverschrijving; on_next_invoice bij een nabetaalde bestelling — zie Betaalroutes
    • method_type: String | het opgeloste betaalmethodetype. Meestal card of sepa_debit, maar er kunnen ook andere typen verschijnen — 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 wanneer het account per kaart of bankoverschrijving wordt belast: 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 pakketcode
  • invalid_term | term is niet monthly of annual
  • product_unavailable | het gevraagde pakket wordt niet aangeboden op dit facturatieplan, of is gearchiveerd (niet meer te koop)
  • no_default_payment_method | het facturatieaccount is niet klaar om te belasten
  • invalid_domain | domain is geen geldige domeinnaam
  • billing_details_incomplete | een workspace met bankoverschrijving waarvan het facturatiecontact onvolledig is

Verwerking (422):

  • no_price_for_plan | geen prijs voor het gevraagde pakket en de gevraagde termijn
  • domain_not_registered | domain is nergens geregistreerd
  • domain_in_use | domain is al in gebruik op een ander hostingaccount
  • domain_dns_zone_exists | de DNS-zone voor domain is van een workspace buiten je facturatiefamilie. Er wordt niets afgerekend
  • 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

De weigeringen van de afrekenroutes die onder Betaalroutes staan, gelden ook.


Betaalroutes

De betaalroute wordt per bestelling bepaald, bij bestellen en resizen. Lees payment (en, bij een nabetaalde bestelling, billing) in het antwoord; Orders legt de routes uit en wat je bij elke weigering moet doen.

Weigeringscodes: 400 billing_details_incomplete; 403 billing_permission_required; 409 bank_transfer_in_progress, bank_transfer_busy, postpay_busy; 422 outstanding_balance_exceeded, in_flight_limit_exceeded, payer_in_dunning, recent_dispute, instant_payment_method_required, bank_transfer_refused, bank_transfer_failed, postpay_route_changed, postpay_pay_open_invoices, postpay_contact_support, postpay_payment_in_progress, postpay_failed, en bij een resize postpay_change_refused en postpay_add_payment_method.


Pakket wijzigen (resize)

PATCH /api/cpanel_accounts/:username

Wijzigt het pakket en verrekent de facturatie opnieuw pro rata. Voor een workspace die per kaart betaalt, wordt de pro rata belast op de opgeslagen betaalmethode, net als bij een resize van een WordPress-site; voor een workspace op een plan dat niet per kaart wordt gefactureerd, wordt de pakketwijziging als bestelling zonder betaling toegepast. 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, invalid_domain of domain_in_use terug.

Params
  • package: String (required) | doel-pakket-key (mini, basic, pro, max) of pakketcode (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 het huidige pakket van het account als het laatst ingestelde pakket, zodat ook een wijziging die nog wordt doorgevoerd meetelt. 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 — anders zou het account boven quota uitkomen. 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 pakketcode
  • 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
  • billing_details_incomplete | een workspace met bankoverschrijving waarvan het facturatiecontact onvolledig is

Conflict (409):

  • resize_in_flight | een eerdere pakketwijziging wordt nog toegepast

Verwerking (422):

  • resize_not_supported | een alleen-mail-account — pakketwijzigingen worden niet aangeboden, alleen opzeggen
  • 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 | het account heeft geen facturatieabonnement om pro rata tegen te verrekenen; neem contact op met support
  • 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 het account kon niet worden opgezocht

De weigeringen van de afrekenroutes die onder Betaalroutes staan, gelden ook.


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. Het account blijft herstelbaar vanuit het CloudPress-dashboard tot delete_scheduled_at, waarna het definitief wordt verwijderd.

Werkt voor zowel hosting- als alleen-mail-accounts.

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 | het account wordt nog vermeld, maar 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. Werkt voor zowel hosting- als alleen-mail-accounts. 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 het account kon niet worden opgezocht

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 onze laatst bekende gegevens 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
    • document_root: String | het absolute pad waarvandaan het domein bestanden serveert, bijv. /home/acmeco01/public_html/shop. Een alias geeft de root van zijn hoofddomein weer. null wanneer die niet gelezen kon worden
  • 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

document_root kan tot tien minuten achterlopen op een wijziging die direct in cPanel is gemaakt.

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:

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
  • connect_method: String (optional, parked en addon) | hoe de DNS van het domein wordt gekoppeld: zone, nameservers of a_record; zie hieronder
  • seed_dns: Boolean (optional, legacy) | false is hetzelfde als connect_method: "a_record". Genegeerd wanneer connect_method is meegegeven
  • mail: Boolean (optional, parked en addon; standaard false) | schrijf ook de mailrecords van het domein. Wordt genegeerd voor een domein dat een Mailspace bedient
  • replace_records: Boolean (optional; standaard false) | vervang bestaande DNS-records die botsen met de records die dit domein nodig heeft. Zonder dit geeft een botsing conflicts_found
  • approved_conflicts: Array<String> (optional, met replace_records) | de record_guid-waarden uit een conflicts_found-antwoord die vervangen mogen worden. Elke andere botsing geeft opnieuw conflicts_found
Teruggegeven params
  • status: String | "accepted"
  • domain: String
  • domain_type: String

Hoe de DNS wordt gekoppeld

connect_method geldt voor een parked- of add-on-domein:

  • zone schrijft de records in de bestaande DNS-zone van deze workspace voor het domein.
  • nameservers betekent dat het domein verhuist naar de nameservers van CloudPress; de zone wordt aangemaakt als die er niet is. Alleen voor een registreerbaar domein (example.com), niet voor een naam eronder (shop.example.com).
  • a_record betekent dat je je DNS elders houdt en zelf een A-record naar de server laat wijzen. Er wordt geen DNS geschreven.

Zonder connect_method wordt DNS alleen geschreven als het domein op onze nameservers staat of deze workspace de zone host. Een subdomein krijgt zijn adresrecords in de zone van het bovenliggende domein wanneer deze workspace die host.

Records die deze API niet heeft geschreven, worden nooit gewijzigd of verwijderd, tenzij je replace_records: true meegeeft.

Botsende DNS-records weigeren het toevoegen

Als records die het domein nodig heeft botsen met bestaande records en je replace_records: true niet hebt meegegeven, geeft het toevoegen 422 conflicts_found en wordt niets gewijzigd, ook niet in cPanel. conflicts noemt de records die in de weg staan (record_guid, type, host, value, site_name, managed_by). Om ze te vervangen, probeer je het opnieuw met replace_records: true en approved_conflicts.

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 domain_already_on_account | het domein staat al op dit account
  • 422 domain_on_other_own_account | het domein staat op een ander cPanel account van deze workspace; de body krijgt er holder_username bij. Verwijder het daar eerst
  • 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 main_domain_temporary | het account heeft nog zijn tijdelijke hoofddomein; stel eerst het hoofddomein in via het dashboard
  • 422 domain_create_failed | de hostingserver weigerde de wijziging
  • 422 invalid_connect_method | connect_method is niet zone, nameservers of a_record, of nameservers is meegegeven voor een naam onder een registreerbaar domein
  • 422 conflicts_found | bestaande DNS-records botsen met de records die het domein nodig heeft; de body krijgt er conflicts bij. Zie hierboven
  • 503 cpanel_unavailable | cPanel is niet geconfigureerd, of de server was niet bereikbaar

De documentroot van een domein wijzigen

PATCH /api/cpanel_accounts/:username/domains/:domain

Laat een add-on-domein of een subdomein naar een andere map wijzen. :domain is een domeinnaam op dit account (anders 404 domain_not_found). Het hoofddomein en aliassen kunnen niet worden gewijzigd (422 document_root_not_editable). PUT werkt hetzelfde.

De map moet al bestaan en een gewone map zijn (geen symlink). Er wordt niets aangemaakt of verplaatst; het domein serveert direct de nieuwe map. Andere domeinen die dezelfde configuratie delen gaan mee en staan in also_affected.

Vereist een gebruiker, facturatiebeheer op de workspace die eigenaar is en een credential die geen OAuth is, net als de andere writes op deze pagina.

Params
  • document_root: String (required) | de nieuwe root relatief aan de homemap van het account, bijv. public_html/shop. De homemap zelf, absolute paden, verborgen mappen en de eigen mappen van cPanel (zoals mail of ssl) worden geweigerd met invalid_document_root
Teruggegeven params (200 OK)
  • status: String | "updated", of "unchanged" wanneer het er al naar wees
  • domain: String
  • document_root: String | de nieuwe root, absoluut (bijv. /home/acmeco01/public_html/shop)
  • previous_document_root: String | de root vóór de wijziging, absoluut
  • also_affected: Array<String> | andere domeinen die dezelfde gewijzigde configuratie delen
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 document_root_not_editable | het domein is het hoofddomein of een alias
  • 422 invalid_document_root | de waarde is geen map binnen de homemap van het account, relatief daaraan opgegeven
  • 422 document_root_not_found | de map bestaat niet op het account, of is geen gewone map. Maak hem eerst aan
  • 422 document_root_update_failed | cPanel accepteerde de nieuwe documentroot niet
  • 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 opruimen

Een domein verwijderen haalt ook de DNS-records weg die deze API ervoor heeft geschreven, en alleen die. Al het andere in de zone, en de zone zelf, blijft staan.

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 temporary_domain_not_removable | het domein is een tijdelijk domein en kan niet worden verwijderd
  • 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

Een account herstellen dat wordt verwijderd heeft geen API-route. Opzeggen en opruimen zijn allebei te scripten, maar een opzegging terugdraaien is een nieuwe aankoop: er wordt een cart voor het pakket opgebouwd en een betaling afgerond, waarna het bestaande hostingaccount weer wordt geactiveerd. Opruimen is onomkeerbaar, dus een onbewaakte opruimjob moet elke opzegging die hij uitvoert als definitief behandelen.

Nodig via de API?

Laat het ons weten wat je automatiseert.