Openbare REST API

Gebruik de openbare REST API van cside om teams en beheerde domeinen in te richten 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. Controleer elk item in data.results 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. Kies alleen de machtigingen die de integratie nodig heeft:

Machtiging	API-toegang
Teams maken (teams:create)	POST /v1/teams/
Teams verwijderen (teams:delete)	DELETE /v1/teams/
Domeinen registreren (domains:create)	POST /v1/domains/
Domeinen verwijderen (domains:delete)	DELETE /v1/domains/

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.

Stuur het token bij elke aanvraag mee:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Tokens blijven geldig totdat een beheerder Alle tokens intrekken selecteert. Hierdoor worden alle API-tokens voor de organisatie onmiddellijk ongeldig.

Aanvraaglimiet

De API accepteert 60 aanvragen per organisatie per minuut. Deze limiet wordt gedeeld door de team- en domeinendpoints. 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.

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:

Status	Betekenis
created	cside heeft de hostnaam geregistreerd en de nieuwe domainId geretourneerd
existing	Hetzelfde team is al eigenaar van de hostnaam. De oorspronkelijke domainId wordt geretourneerd
invalid	cside heeft de hostnaam niet geregistreerd. Controleer code en message

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.

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:

Code	Betekenis
empty_domain	De invoer is leeg
invalid_domain	De hostnaam is ongeldig
public_suffix_domain	De invoer is een public suffix en geen registreerbare hostnaam
internal_domain	De hostnaam is gereserveerd of niet toegestaan
reserved_ip	DNS zet de hostnaam om naar een gereserveerd IP-adres
wildcard_conflict	Een bestaand wildcarddomein dekt deze hostnaam al
subdomain_conflict	Een bestaande domeinconfiguratie bevat dit subdomein al
domain_already_licensed	Een ander team beheert de hostnaam al
internal_error	cside kon het domein niet valideren of maken

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.

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."
}

HTTP-status	Veelvoorkomende foutcodes	Actie
400	invalid_request	Controleer de JSON-body, verplichte velden, ID-tekenreeksen, en itemlimieten
401	unauthorized	Controleer het bearertoken en of alle organisatietokens zijn ingetrokken
403	insufficient_scope, enterprise_required, opschortingsfouten	Controleer tokenmachtigingen, abonnementstoegang, en accountstatus
404	team_not_found	Controleer of het team-ID bij de organisatie van het token hoort
409	team_name_exists	Kies een unieke teamnaam of gebruik het bestaande team
409	team_subscription_attached	Zeg het Stripe-abonnement van het team op voordat je het verwijdert; neem contact op met ondersteuning als de fout aanhoudt
429	rate_limited	Probeer het met back-off opnieuw na het huidige limietvenster
503	rate_limit_unavailable, domain_deletion_unavailable, team_deletion_unavailable	Probeer het later opnieuw. Neem contact op met de ondersteuning van cside als de fout aanhoudt

Beveiligingschecklist

• Genereer een afzonderlijk token 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 alle organisatietokens onmiddellijk in als er één is blootgesteld
• Behandel geretourneerde team- en domein-ID’s als tekenreeksen

Gerelateerde documentatie

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