Ga naar inhoud

Authenticatie

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

Authorization: Token {{ SuperSpace API Token }}

Authorization: Bearer {{ SuperSpace 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):

Credential Identiteit Admin‑rechten? Gelden OAuth-scopes? Opmerkingen
User API key Een gebruiker (heeft toegang tot de accounts waartoe die gebruiker behoort) Als de sleutel als admin is gemarkeerd Nee (omzeilt scopecontroles) Optionele IP-toegangslijst.
System API key Een account (alleen systeembeheerd) Als als admin gemarkeerd Nee Het account komt van de drager van de sleutel — vereist geen X-Auth-Account; het IP moet op de systeemtoegangslijst staan.
OAuth 2.1 access token Een gebruiker, gebonden aan één (account, brand) Nooit Ja — fail-closed Uitgegeven via de OAuth 2.1 autorisatieserver.

Trial-accounts kunnen de API niet gebruiken

De authenticatie weigert elke credential die naar een trial-account verwijst, voor zowel sessie/API-sleutel- als OAuth-tokens.

IP-beperking

Je kunt de toegang per IP beperken tot een specifieke API-sleutel in de SuperSpace 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: {{ SuperSpace 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.
  • Sommige endpoints vereisen de header en geven 400 {"errors":["Missing X-Auth-Account"]} terug wanneer hij ontbreekt — Orders, Carts, Subscriptions, Users, Webhooks, het aanmaken van DNS-zones, en alle endpoints voor domeinregistratie.
  • 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.

OAuth audience binding (RFC 8707)

Een OAuth-token dat is aangemaakt met een resource-indicator (bijvoorbeeld een token uitgegeven voor de MCP-server op /mcp) wordt op /api/* geweigerd met HTTP 401 en een JSON-body — niet de bovenstaande vorm met lege body en WWW-Authenticate:

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

/api geeft nooit resource-gebonden tokens uit, dus elk token dat een resource draagt is aangemaakt voor een andere audience en kan /api niet bereiken.

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

Index-endpoints accepteren de queryparameters page en per_page.

Param Type Standaard Opmerkingen
page Integer 1 Paginanummer
per_page Integer 50 Records per pagina, begrensd tot een maximum van 100

Rate limiting

Verzoeken zijn beperkt tot 600 per 10 minuten, per credential. Bij overschrijding van de limiet wordt 429 met een lege body teruggegeven.

Foutreacties

Status Wanneer dit optreedt
400 Ontbrekende verplichte header; ongeldige/no-op-params; validatiefouten bij order- en site-resize (onbekende variant/locatie/term/product); no_default_payment_method; OAuth picker-/DCR-fouten
401 Authenticatie mislukt (geen/ongeldig token, IP geblokkeerd, trial-account, accountmismatch); admin-only endpoint met een niet-admin-credential
402 Dienst opgeschort vanwege een onbetaalde factuur (service_suspended); registrar fee-gate (payment_required)
403 Onvoldoende rol ({"errors":["Not Authorized"]}); OAuth-scopefout (insufficient_scope); Shield niet in abonnement / premium vereist
404 Resource niet gevonden of niet toegankelijk voor dit token
409 Conflict — Bunny-resource niet actief (cdn_not_active, shield_not_active); registrar-proces al onderweg (registration_busy)
422 Validatiefout of rechtenbeperking (bijv. overgeërfde rol, alleen voor resellers, resize-beperkingen); billing-settle-bewaking op een net aangemaakte site (billing_settling); cart-betaling kon niet worden gestart (cart_pay_failed)
429 Rate limit overschreden (600 / 10 min)
502 Upstream-fout (Bunny CDN/Shield, of domeinregistrar)
503 Functie uitgeschakeld (feature_disabled, de domain-registration-flag) of geen registrar geconfigureerd voor een TLD (registrar_unavailable)

Functie- en plan-gating

De enige feature flag die API-endpoints gate't is domain-registration (geeft 503 feature_disabled terug wanneer uit). Shield is plan-gated (403 shield_not_in_plan, of shield_premium_required voor premium-only writes). CDN/Shield nog niet voorzien op Bunny geeft 409 terug (cdn_not_active / shield_not_active).

Asynchrone bewerkingen

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

  • Tasks — PHP-versiewijzigingen, back-ups, restores, herstarten, site-domeinen toevoegen/verwijderen, cachewijzigingen, het verwijderen van een accountrol, en accountverwijdering maken een Task aan. Poll 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

SuperSpace 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

Teruggegeven params
  • version: String | Informatie over de API-versie
  • logged_in_as: String | Jouw gebruikers-ID
  • account_scoped: String | Als je met een account hebt geauthenticeerd, is dit jouw ID.
  • locations: Array
    • id: String
    • name: String
  • products: Array
    • id: String
    • name: String
    • description: String
  • php: Array | [] wanneer er geen versies beschikbaar zijn
    • id: Integer
    • label: String
    • is_default: Boolean
Voorbeeld 
curl -H "Authorization: Bearer $SUPERSPACE_TOKEN" \
  https://your-instance/api/about