Openbare REST API

Gebruik de openbare REST API van cside om teams te maken of te verwijderen, domeinen te beheren en checkout-pagina-selectors toe te voegen vanuit een backendworkflow. De API gebruikt JSON via HTTPS en een bearertoken op organisatieniveau.

Basis-URL: https://api.cside.com

Inrichtingsproces

Het maken van een team en het registreren van domeinen zijn afzonderlijke handelingen:

1. Maak een API-token voor de organisatie met de vereiste machtigingen
2. Roep POST /v1/teams/ aan en sla de geretourneerde teamId op
3. Roep POST /v1/domains/ aan met die teamId en maximaal 100 hostnamen
4. Roep POST /v1/payment-pages/ aan om checkout-pagina-selectors aan het team toe te voegen
5. Controleer elk antwoord voordat u de inrichting als voltooid beschouwt

Als de domeinregistratie mislukt, blijft het team beschikbaar. De API draait een geslaagde teamcreatie niet terug.

Beschikbaarheid en authenticatie

Een organisatiebeheerder kan een token genereren via **Organisatie-instellingen

Algemeen** in het cside-dashboard. Selecteer Token genereren, geef het token een naam (bijvoorbeeld de integratie waarbij het hoort) en kies alleen de machtigingen die de integratie nodig heeft:

teams:create of teams:delete staat ook zoeken met een niet-leeg name-filter toe. domains:create of domains:delete staat zoeken met een niet-leeg domain-filter toe. Ongefilterde lijsten vereisen teams:read of domains:read; integraties voor alleen lezen hebben daarmee geen schrijfrechten nodig. Lees- en schrijfaanvragen delen de limiet van 60 aanvragen per minuut per organisatie.

Het dashboard toont elk token één keer. Sla het op in een server-side secretmanager voordat u het dialoogvenster sluit. Stel het niet beschikbaar in browsercode, commit het niet naar versiebeheer, en schrijf het niet naar applicatielogs.

Tokens hebben de vorm cside_oatv2_<id>_<secret>. Het deel <id> identificeert het token in de dashboardlijst en in de auditlogs; de rest is het geheim.

Stuur het token bij elke aanvraag mee:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Tokens beheren en intrekken

Organisatie-instellingen > Algemeen toont elk actief token met zijn Naam, gemaskeerde Token-prefix, Scopes, Aangemaakt-datum en Laatst gebruikt-datum. Een organisatie kan maximaal 50 actieve tokens hebben. Als de limiet is bereikt, trekt u een ongebruikt token in voordat u een nieuw token genereert.

Een token blijft geldig totdat het wordt ingetrokken. U kunt tokens op twee manieren intrekken:

• Intrekken voor één token in de lijst. Alleen dat token werkt niet meer, en andere integraties blijven draaien.
• Alle tokens intrekken om alle API-tokens voor de organisatie in één keer ongeldig te maken, inclusief tokens die niet in de lijst staan.

Tokens die zijn gegenereerd voordat de tokenlijst bestond, staan niet in de lijst. Ze blijven werken, maar Alle tokens intrekken is de enige manier om ze in te trekken.

Het maken van een token, het intrekken van één token en Alle tokens intrekken worden vastgelegd in het auditlog van de organisatie als org.api_token.create, org.api_token.revoke en org.api_secret.rotate.

Aanvraaglimiet

De API accepteert 60 aanvragen per organisatie per minuut. Deze limiet wordt gedeeld door de team-, domein- en betaalpagina-endpoints. Een aanvraag boven de limiet retourneert 429 met de foutcode rate_limited. Probeer het met back-off opnieuw nadat de volgende minuut is begonnen.

Een team maken

Gebruik POST /v1/teams/ om een team onder de organisatie van het token te maken.

curl --request POST \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Acme Production"
  }'

De teamnaam moet:

• 3 tot 32 tekens bevatten
• Letters, cijfers, underscores, spaties, of apostroffen gebruiken
• Uniek zijn binnen de organisatie

Koppeltekens worden niet geaccepteerd in teamnamen.

Een geslaagde aanvraag retourneert 201 Created:

{
  "data": {
    "teamId": "1897425263682514944"
  }
}

Sla data.teamId op. U hebt deze nodig om domeinen voor het team te registreren of verwijderen.

Een conflict retourneert 409 team_name_exists met het bestaande team, dus een herhaalde aanroep is veilig en levert nog steeds een bruikbaar ID op:

{
  "error": "team_name_exists",
  "message": "Team with name `Acme Production` already exists in this organization.",
  "data": {
    "teamId": "1897425263682514944"
  }
}

Door een team te maken, wordt automatische domeinonboarding niet ingeschakeld. Deze mogelijkheid wordt voor elk team afzonderlijk geconfigureerd en is standaard uitgeschakeld.

Domeinen registreren

Gebruik POST /v1/domains/ om 1 tot 100 hostnamen van beheerde domeinen voor een team te registreren. team_id is vereist wanneer u een API-token voor een organisatie gebruikt.

curl --request POST \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "checkout.example.com",
      "app.example.com"
    ]
  }'

Stuur hostnamen zonder protocol, poort, pad, querytekenreeks, of fragment. cside verwijdert witruimte en zet geaccepteerde hostnamen om naar kleine letters.

Elk item registreert exact de hostnaam die u verstuurt. De API maakt geen wildcarddomein. Neem daarom elke benodigde hostnaam op, zoals zowel example.com als www.example.com.

Het endpoint retourneert 200 OK met één resultaat voor elke invoer, in dezelfde volgorde:

{
  "data": {
    "results": [
      {
        "status": "created",
        "input": "checkout.example.com",
        "domain": "checkout.example.com",
        "domainId": "1897425263682514945"
      },
      {
        "status": "existing",
        "input": "app.example.com",
        "domain": "app.example.com",
        "domainId": "1897425263682514946"
      },
      {
        "status": "invalid",
        "input": "not a hostname",
        "code": "invalid_domain",
        "message": "Domain is invalid."
      }
    ],
    "totals": {
      "created": 1,
      "existing": 1,
      "invalid": 1
    }
  }
}

De aanvraag kan zowel geslaagde als ongeldige resultaten bevatten en toch 200 OK retourneren. Controleer elk resultaat:

U kunt aanvragen voor domeinen die al voor hetzelfde team zijn gemaakt veilig opnieuw proberen. Ze retourneren existing in plaats van een duplicaat te maken. Een hostnaam die door een ander team wordt beheerd, retourneert invalid met domain_already_licensed.

Als de domeinen zijn opgeslagen maar cside de configuratie niet volledig naar het distributienetwerk kon doorvoeren, retourneert de aanvraag 503 domain_registration_unavailable met het bericht “Domains saved, but synchronization is incomplete. Retry to synchronize them.” Stuur dezelfde aanvraag opnieuw: de opgeslagen hostnamen komen terug als existing en de synchronisatie wordt opnieuw geprobeerd.

Nieuwe domeinen krijgen automatisch beheerde bescherming. Er is geen afzonderlijke API-aanroep voor activering nodig. Het kan even duren voordat de configuratie het distributienetwerk bereikt.

Validatiecodes voor domeinen

Een invalid resultaat kan een van deze codes bevatten:

Betaalpagina’s toevoegen

Gebruik POST /v1/payment-pages/ om één checkout-pagina-selector aan een bestaand team toe te voegen. team_id is vereist wanneer u een API-token voor een organisatie gebruikt. Voor een token dat tot één team beperkt is, is het optioneel; als u het meestuurt, moet het overeenkomen met het team van het token.

curl --request POST \
  --url https://api.cside.com/v1/payment-pages/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "payment_page": "checkout.example.com/checkout"
  }'

Stuur payment_page als een canonieke host/pad-selector zonder https://, poort of volledige URL. Gebruik bijvoorbeeld checkout.example.com/checkout, niet https://checkout.example.com/checkout. cside verwijdert omringende witruimte, querytekenreeksen en afsluitende schuine strepen voordat de selector wordt opgeslagen. Een #-fragment wordt bewaard zoals verzonden, zodat single-page apps die hun betaalpagina via een fragment routeren erop kunnen matchen. Een selector die witruimte bevat, zoals checkout.example.com/check out, wordt afgewezen met 400 invalid_payment_page.

De selector gebruikt hetzelfde patroonformaat als het dashboard. Een team kan maximaal 500 checkout-pagina-selectors hebben. Het endpoint registreert geen domein. Registreer de hostnaam daarom eerst met POST /v1/domains/ als het team deze nog niet beheert.

Het endpoint retourneert 200 OK:

{
  "data": {
    "status": "created",
    "teamId": "1897425263682514944",
    "paymentPage": "checkout.example.com/checkout"
  }
}

Dezelfde selector opnieuw toevoegen is veilig en retourneert status: "existing". Een nieuwe selector retourneert status: "created". Als het team overeenkomende domeinen bezit, werkt cside hun checkout-paginaprojecties en bijbehorende configuratie bij nadat de selector op teamniveau is opgeslagen.

cside voor het team laden

Gebruik de teamId die bij het maken van het team is geretourneerd in de standaard-URL van het cside-script. Gebruik geen domainId.

<script
  src="https://[your-team-id].csidetm.com/client.js"
  referrerpolicy="origin">
</script>

De hostnaam van de pagina moet zijn geregistreerd onder hetzelfde team-ID als in de script-URL. Een ontbrekende registratie of een afwijkend team retourneert 403. Probeer het na korte tijd opnieuw als dit direct na de registratie gebeurt. Neem contact op met de ondersteuning van cside als het probleem aanhoudt.

Voor standaardmonitoring is geen CNAME van de klant of omleiding van verkeer nodig. Als uw site een restrictief Content Security Policy heeft, volgt u de handleiding voor CSP-configuratie om *.csidetm.com toe te staan.

Automatische domeinonboarding

Automatische domeinonboarding is een optionele teammogelijkheid voor implementaties die het standaard bootstrap-script van cside laden. Deze is standaard uitgeschakeld voor nieuwe teams. Neem contact op met uw cside-vertegenwoordiger als u deze wilt inschakelen.

Wanneer de mogelijkheid is ingeschakeld en een niet-geregistreerde hostnaam de teamspecifieke bootstrap /client.js of /script.js laadt, stuurt cside de verwijzende hostnaam door hetzelfde validatie- en registratieproces voor domeinen. Behoud het standaardattribuut referrerpolicy="origin", zodat de oorsprong van de pagina beschikbaar is zonder het pad of de querytekenreeks bloot te stellen.

De aanvraag die de niet-geregistreerde hostnaam detecteert, wordt niet opnieuw geprobeerd. De registratie is van invloed op een latere scriptaanvraag nadat de configuratie is doorgevoerd. Automatisch geregistreerde domeinen verschijnen in de domeininventaris van het team, net als domeinen die via de API zijn geregistreerd.

Automatische onboarding maakt geen teams, en aanvragen aan andere cside-endpoints registreren geen hostnaam. Gebruik het expliciete API-proces als u vóór de implementatie van het script een resultaat voor elk domein nodig hebt. Automatische onboarding geldt voor het standaardmonitoringscript en schakelt het verzamelen van Device Intelligence-gegevens niet in.

Teams weergeven

Gebruik GET /v1/teams/ met een organisatietoken. Teamgebonden tokens kunnen dit endpoint niet aanroepen. Laat name weg om teams op te sommen of geef een exacte, hoofdlettergevoelige naam op. Spaties aan het begin en einde worden verwijderd, net als bij het maken. Hernoemde teams kunnen dezelfde naam hebben, dus verwerk altijd een array met resultaten. Opgeschorte teams worden meegenomen. Zonder overeenkomst volgt 200 OK met een lege data-array.

curl --get \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "name=Acme Production"

{
  "data": [
    {
      "id": "1897425263682514944",
      "name": "Acme Production",
      "createdAt": "2026-07-07T10:00:00Z",
      "suspended": false
    }
  ],
  "next_cursor": null
}

Domeinen weergeven

Gebruik GET /v1/domains/ om domeinen op te sommen. Laat met een organisatietoken team_id weg voor de hele organisatie of geef één team op. Een teamtoken kan alleen zijn eigen team lezen, ook zonder team_id. Een onbekend of ontoegankelijk team geeft 404 team_not_found. Het optionele filter domain zoekt een exacte hostnaam.

curl --get \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "team_id=1897425263682514944"

{
  "data": [
    {
      "id": "1897425263682514945",
      "domain": "checkout.acme.com",
      "teamId": "1897425263682514944",
      "managed": true,
      "wildcard": false,
      "suspended": false,
      "createdAt": "2026-07-07T10:00:00Z"
    }
  ],
  "next_cursor": null
}

Resultaten bevatten beheerde en onbeheerde domeinen. id is de domainId die domeinregistratie teruggeeft. Controleer managed voordat u dat ID met DELETE /v1/domains/ gebruikt: alleen beheerde domeinen kunnen via deze API worden verwijderd. Zonder overeenkomende hostnaam is de data-array leeg.

Door resultaten bladeren

Beide endpoints accepteren limit (1 tot 100, standaard 50) en een optionele cursor. Resultaten staan op aanmaaktijd, oudste eerst, met ID als tweede sorteersleutel. Elk 200 OK-antwoord bevat een data-array en next_cursor. Ga door totdat next_cursor null is.

Behandel de cursor als een ondoorzichtige waarde en URL-encodeer deze bij het terugsturen. Houd dezelfde tokenscope en filters tussen pagina’s. Een ongeldige cursor of een cursor uit een andere zoekopdracht of tenant geeft 400 invalid_cursor; begin die zoekopdracht opnieuw zonder cursor.

curl --get \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "team_id=1897425263682514944" \
  --data-urlencode "cursor=NEXT_CURSOR"

Domeinen verwijderen

Gebruik DELETE /v1/domains/ met de domainId-waarden die door de domeinregistratie zijn geretourneerd. Stuur geen hostnamen naar dit endpoint.

curl --request DELETE \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "1897425263682514945",
      "1897425263682514946"
    ]
  }'

U kunt 1 tot 100 domein-ID’s versturen. Een geslaagde aanvraag retourneert geordende deelresultaten:

{
  "data": {
    "results": [
      {
        "status": "deleted",
        "domainId": "1897425263682514945",
        "domain": "checkout.example.com"
      },
      {
        "status": "not_found",
        "domainId": "1897425263682514999"
      }
    ],
    "totals": {
      "deleted": 1,
      "not_found": 1
    }
  }
}

Verwijdering is idempotent. Een onbekend ID, een al verwijderd domein, of een domein buiten het doelteam retourneert not_found zonder informatie over een ander team te onthullen.

Een team verwijderen

Gebruik DELETE /v1/teams/ om een team en alle bijbehorende domeinen permanent te verwijderen. Het verzoek vereist een organisatietoken met Teams verwijderen (teams:delete). Deze toestemming omvat het verwijderen van domeinen; domains:delete alleen is niet voldoende om een team te verwijderen. Genereer een nieuw token om deze toestemming aan een bestaande integratie toe te voegen. Tokens die tot één team beperkt zijn, worden niet geaccepteerd.

Stuur de teamId die je bij het maken van het team hebt ontvangen als team_id, een decimale tekenreeks tussen aanhalingstekens. Je hoeft de domeinen niet op te sommen of afzonderlijk te verwijderen.

curl --request DELETE \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944"
  }'

Een geslaagd verzoek retourneert 200 OK. deletedDomains is het aantal verwijderde domeinen:

{
  "data": {
    "status": "deleted",
    "teamId": "1897425263682514944",
    "deletedDomains": 2
  }
}

Een team met een gekoppeld Stripe-abonnement retourneert 409 team_subscription_attached. Zeg het abonnement op voordat je het team verwijdert. Als het al is opgezegd en de fout aanhoudt, neem dan contact op met de ondersteuning van cside.

Een onbekend team, een team buiten de organisatie van het token of een al verwijderd team retourneert 404 team_not_found. Het herhalen van een geslaagde verwijdering verwijdert niets anders. Als het opschonen mislukt, retourneert de API 503 team_deletion_unavailable. Probeer het later opnieuw en neem contact op met ondersteuning als de fout aanhoudt.

Enterprise-toegang wordt bij elk verzoek gecontroleerd. Als je het laatste actieve Enterprise-team van de organisatie verwijdert, retourneren volgende verzoeken aan de publieke API, inclusief herhaalde pogingen, 403 enterprise_required.

Fouten op aanvraagniveau

Fouten op aanvraagniveau hebben deze structuur:

{
  "error": "insufficient_scope",
  "message": "Token is missing the domains:create scope."
}

Beveiligingschecklist

• Genereer een afzonderlijk token met een eigen naam voor elke backendintegratie
• Verleen alleen de machtigingen die de integratie nodig heeft
• Bewaar tokens in een server-side secretmanager
• Stel tokens nooit beschikbaar in browsercode, URL’s, versiebeheer, of logs
• Trek een token onmiddellijk in als het is blootgesteld; gebruik Alle tokens intrekken als u niet weet welk token is gelekt of als het token ouder is dan de tokenlijst
• Bekijk de kolom Laatst gebruikt en trek tokens in die niet meer worden gebruikt
• Behandel geretourneerde team- en domein-ID’s als tekenreeksen

Gerelateerde documentatie

• Interactieve API-referentie
• Uw domein toevoegen
• Het cside-script toevoegen
• Dashboardinstellingen