OAuth 2.1
CloudPress draait een standaard OAuth 2.1-autorisatieserver. Gebruik die voor apps van derden die namens een gebruiker handelen; gebruik API-sleutels voor first-party- / server-to-server-integraties.
OAuth-accesstokens zijn nooit admin en zijn fail-closed: een endpoint dat geen scope declareert, is niet beschikbaar via OAuth, en een token waaraan een vereiste scope ontbreekt, wordt geweigerd. Session- en API-sleutel-credentials omzeilen scope- controles volledig.
Authorization Server Metadata
De metadata is per merk, afgeleid van de request-host.
GET /.well-known/oauth-authorization-server
Teruggegeven params
- issuer: String
- authorization_endpoint: String |
https://<host>/oauth/authorize - token_endpoint: String |
https://<host>/oauth/token - revocation_endpoint: String |
https://<host>/oauth/revoke - introspection_endpoint: String |
https://<host>/oauth/introspect - registration_endpoint: String |
https://<host>/oauth/registration - response_types_supported: Array |
["code"] - grant_types_supported: Array |
["authorization_code", "refresh_token"] - code_challenge_methods_supported: Array |
["S256"] - token_endpoint_auth_methods_supported: Array |
["none"] - scopes_supported: Array | zie Scopes
- service_documentation: String
Alleen none wordt geadverteerd
Deze server geeft uitsluitend publieke PKCE-clients uit, dus
token_endpoint_auth_methods_supported adverteert alleen ["none"].
Confidential-methoden zoals client_secret_post worden niet geaccepteerd; registreren
met een van die methoden geeft 400.
Flows
- Grant types: alleen
authorization_codeenrefresh_token. - PKCE is verplicht (alleen
S256). - Refresh tokens roteren — het vorige refresh token wordt bij gebruik ingetrokken.
- Geen OpenID Connect — er is geen
/.well-known/openid-configuration, geen userinfo, geen ID-tokens. - Inloggen — een gebruiker die niet is ingelogd, logt eerst in en keert dan terug naar het autorisatiescherm om een workspace te kiezen en toestemming te geven.
- Merkisolatie — een token is gebonden aan het merk (hostnaam) waaronder het is uitgegeven en wordt op elk ander merk geweigerd. Het autorisatiescherm toont de niet-proef-workspaces van de gebruiker op dat merk.
Tokenintrekking bij rolwijziging
Het verwijderen van de rol van een gebruiker op een account trekt diens OAuth-tokens (en sessies) voor dat account in.
Dynamic Client Registration (DCR)
POST /oauth/registration (RFC 7591)
Er worden alleen publieke PKCE-clients uitgegeven. Een
token_endpoint_auth_method die niet "none" is, laat de registratie niet
mislukken — de waarde wordt stilzwijgend omgezet naar "none", en de reactie
geeft "none" terug zonder client_secret. Registreer je dus als publieke
client en vertrouw op PKCE (S256); een via DCR uitgegeven secret voegt daar
niets aan toe.
Fouten
- 429
{"error":"too_many_requests", ...}| per-IP-limiet van 50 registraties / uur overschreden
Scopes
Er zijn geen standaardscopes — de aanwezigheid van een token is identiteit, en elke resource-scope is opt-in.
| Scope | Verleent |
|---|---|
sites:read |
Site-reads + geneste site-reads (show/index, back-uplijst, cachestatus, CDN-status, variantenlijst, taken, edge-rules-lijst, Shield-reads, logs, metrics, overzicht/verzendlogs/verbruik van transactionele e-mail) |
sites:write |
Site- + geneste site-writes (create/update/destroy, back-ups, cache, restart, restore, edge rules, Shield-writes, certificaten, site-domain-CRUD, variantwijziging, SSH-gegevens opnieuw genereren, instellingen/blokkade-opheffing/DNS-hercontrole van transactionele e-mail) — plus beide kanten van back-upexport (POST en GET /api/sites/{site-id}/backups/{volume-id}/export; het uitlezen van de status vereist de write-scope, omdat het een presigned URL naar de volledige back-up teruggeeft) |
domains:read |
Domeinen list/show/query/available; domain-registration index/show/check/suggestions; contacts/hosts/processes reads |
domains:write |
Domain-registration-mutaties; domain-contact create/update/destroy/resend; host/process writes |
dns:read |
DNS-zones index/show/dns_stats; DNS-records index/show |
dns:write |
DNS-zone & -record create/update/destroy |
mailspace:read |
Mailspace list/show, plus elke read binnen een mailomgeving: mailboxen (inclusief de controle op beschikbaarheid van een adres), app-wachtwoorden, mailregels, afwezigheidsberichten, doorsturen van mailboxen, aliassen, groepen, mailinglijsten, anonieme e-mailadressen, extra domeinen en hun DNS-records, de status van domeinverificatie, bezorglogs, gearchiveerde berichten (inclusief het downloaden van het ruwe bericht) en de lijst met te herstellen mailboxen |
mailspace:write |
Mailspace aanschaffen, pakket wijzigen en soft-delete, plus elke write binnen een mailomgeving: mailbox-CRUD/herstel/definitief verwijderen, app-wachtwoorden, mailregels, afwezigheidsberichten, doorsturen van mailboxen, aliassen, groepen, mailinglijsten, anonieme e-mailadressen, CRUD op extra domeinen en de DNS-hercontrole, domeinverificatie, mailboxherstel — en het onomkeerbaar direct definitief verwijderen van een met soft delete verwijderde mailomgeving en van een mailbox |
billing:read |
Orders index/show; subscriptions index/show; komende kosten; carts show |
cpanel:read |
cPanel-account list/show en de domeinenlijst van het account (GET /api/cpanel_accounts, GET /api/cpanel_accounts/{username}, GET /api/cpanel_accounts/{username}/domains) — alleen reads; elke cPanel-write is met geen enkel OAuth-token bereikbaar (zie hieronder). cPanel wordt per workspace ingeschakeld, dus deze endpoints geven 403 cpanel_not_enabled terug waar dat niet is gebeurd |
GET /api/about accepteert elk geldig token, ongeacht scope.
Endpoints die niet beschikbaar zijn via OAuth
Deze declareren geen scope en zijn fail-closed — ze vereisen een session- of
API-sleutel-credential en geven 403 endpoint not available via OAuth terug voor elk
OAuth-token:
Niet bereikbaar met OAuth-tokens
Geen enkele scope geeft toegang tot de onderstaande endpoints, dus een app van derden kan namens jou geen betaalde dienst bestellen, resizen of opzeggen, hoe breed je ook toestemming hebt gegeven.
- Account-CRUD & account-rollen
- API-sleutels
- Gebruikers en
user_roles - De globale taken-endpoints (
GET /api/tasks/:id) - SSO (per-site en top-level)
-
Elke cPanel-account-write. Er is geen
cpanel:write-scope, dus deze zijn allemaal alleen via sessie of API-sleutel bereikbaar:POST /api/cpanel_accounts,PATCH /api/cpanel_accounts/{username}enDELETE /api/cpanel_accounts/{username}PATCH /api/cpanel_accounts/{username}/passwordPOST /api/cpanel_accounts/{username}/purgePOST /api/cpanel_accounts/{username}/domainsenDELETE /api/cpanel_accounts/{username}/domains/{domain}POST /api/cpanel_accounts/{username}/session
cpanel:readdekt alleen de list/show-reads en de domeinenlijst. (Mailspace stelt zijn writes daarentegen wel beschikbaar — ondermailspace:write.) - De domain-order-endpoints:POST /api/orders/domainenPOST /api/domain_registrations/:id/registrant_change(beide plaatsen een betaalde order en vereisen een gebruiker-gescopete API-sleutel —registrant_changevalt niet onder dedomains:write-scope) - Alle write-operaties op orders/sites-facturatie (er is geenbilling:write-scope)
Scope-handhavingsfouten
Fouten
- 401
{"error":"invalid_token","error_description":"token audience is not valid for /api"}| het token draagt eenresource-audience (RFC 8707) die voor een andere resource is uitgegeven (bijv. de MCP-server) —/apiweigert het vóór de scope-controle - 403
{"error":"insufficient_scope","error_description":"requires scope: <required>"}| met headerWWW-Authenticate: Bearer error="insufficient_scope", scope="<required>" - 403
{"error":"insufficient_scope","error_description":"endpoint not available via OAuth"}| endpoint declareert geen scope