Ga naar inhoud

OAuth 2.1

SuperSpace 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 | ["client_secret_basic", "client_secret_post", "none"]
  • scopes_supported: Array | zie Scopes
  • service_documentation: String

Flows

  • Grant types: alleen authorization_code en refresh_token.
  • PKCE is verplicht (alleen S256).
  • Refresh tokens roteren — het vorige refresh token wordt bij gebruik ingetrokken. De rotatie gaat pas door zodra het nieuwe access token is gevalideerd tegen de merk-, proef- en rolcontroles.
  • Geen OpenID Connect — er is geen /.well-known/openid-configuration, geen userinfo, geen ID-tokens. De OIDC-gem is alleen aangesloten voor Dynamic Client Registration.
  • Merkisolatie — een token is gebonden aan het merk (hostnaam) waaronder het is uitgegeven en wordt op elk ander merk geweigerd. Het autorisatiescherm toont alleen de niet-proefaccounts van de gebruiker op het huidige 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)

Alleen publieke PKCE-clients zijn toegestaan — token_endpoint_auth_method moet "none" zijn.

Fouten
  • 400 {"error":"invalid_client_metadata", ...} | token_endpoint_auth_method is niet "none"
  • 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)
sites:write Site- + geneste site-writes (create/update/destroy, back-ups, cache, restart, restore, edge rules, Shield-writes, certificaten, site-domain-CRUD, variantwijziging)
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
billing:read Orders index/show; subscriptions index/show; carts show

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:

  • Account-CRUD & account-rollen
  • API-sleutels
  • Gebruikers en user_roles
  • De globale taken-endpoints (GET /api/tasks/:id)
  • SSO (per-site en top-level)
  • Rapporteren van een taakresultaat (POST /api/webhooks/task/{task-id})
  • De domain-order-endpoints: POST /api/orders/domain en POST /api/domain_registrations/:id/registrant_change (beide plaatsen een betaalde order en vereisen een gebruiker-gescopete API-sleutel — registrant_change is bewust uitgesloten van de domains:write-scope)
  • Alle write-operaties op orders/sites-facturatie (er is bewust geen billing:write-scope)

Scope-handhavingsfouten

Fouten
  • 401 {"error":"invalid_token","error_description":"token audience is not valid for /api"} | het token draagt een resource-audience (RFC 8707) die voor een andere resource is uitgegeven (bijv. de MCP-server) — /api weigert het vóór de scope-controle
  • 403 {"error":"insufficient_scope","error_description":"requires scope: <required>"} | met header WWW-Authenticate: Bearer error="insufficient_scope", scope="<required>"
  • 403 {"error":"insufficient_scope","error_description":"endpoint not available via OAuth"} | endpoint declareert geen scope