API REST publique

Utilisez l’API REST publique de cside pour créer ou supprimer des équipes, gérer des domaines et ajouter des sélecteurs de pages de paiement depuis un flux de travail backend. L’API utilise JSON sur HTTPS et un jeton Bearer associé à l’organisation.

URL de base : https://api.cside.com

Flux de provisionnement

La création d’une équipe et l’enregistrement des domaines sont des opérations distinctes :

1. Créez un jeton d’API d’organisation avec les autorisations requises
2. Appelez POST /v1/teams/ et enregistrez le teamId renvoyé
3. Appelez POST /v1/domains/ avec ce teamId et jusqu’à 100 noms d’hôte
4. Appelez POST /v1/payment-pages/ pour ajouter des sélecteurs de pages de paiement à l’équipe
5. Vérifiez chaque réponse avant de considérer le provisionnement comme terminé

Si l’enregistrement des domaines échoue, l’équipe reste disponible. L’API n’annule pas la création réussie d’une équipe.

Disponibilité et authentification

Un administrateur de l’organisation peut générer un jeton dans Paramètres de l’organisation > General sur le tableau de bord cside. Sélectionnez Générer un jeton, donnez un nom au jeton (par exemple celui de l’intégration à laquelle il appartient) et choisissez uniquement les autorisations dont l’intégration a besoin :

teams:create ou teams:delete autorise aussi une recherche avec un filtre name non vide. domains:create ou domains:delete autorise une recherche avec un filtre domain non vide. Les listes sans filtre nécessitent teams:read ou domains:read ; ces droits suffisent aux intégrations en lecture seule. Lectures et écritures partagent la limite de 60 requêtes par minute et par organisation.

Le tableau de bord n’affiche chaque jeton qu’une seule fois. Enregistrez-le dans un gestionnaire de secrets côté serveur avant de fermer la boîte de dialogue. Ne l’exposez pas dans le code du navigateur, ne l’ajoutez pas au contrôle de version et ne l’écrivez pas dans les journaux de l’application.

Les jetons ont la forme cside_oatv2_<id>_<secret>. La partie <id> identifie le jeton dans la liste du tableau de bord et dans les journaux d’audit ; le reste est le secret.

Envoyez le jeton avec chaque requête :

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Gérer et révoquer les jetons

Paramètres de l’organisation > General liste chaque jeton actif avec son Nom, son préfixe de Jeton masqué, ses Portées, sa date de Création et sa date de Dernière utilisation. Une organisation peut avoir jusqu’à 50 jetons actifs. Lorsque la limite est atteinte, révoquez un jeton inutilisé avant d’en générer un nouveau.

Un jeton reste valide jusqu’à sa révocation. Vous pouvez révoquer des jetons de deux façons :

• Révoquer un seul jeton depuis la liste. Seul ce jeton cesse de fonctionner, les autres intégrations continuent de s’exécuter.
• Révoquer tous les jetons pour invalider d’un coup tous les jetons d’API de l’organisation, y compris ceux qui n’apparaissent pas dans la liste.

Les jetons générés avant l’existence de la liste des jetons n’y apparaissent pas. Ils continuent de fonctionner, mais Révoquer tous les jetons est le seul moyen de les révoquer.

La création d’un jeton, la révocation d’un seul jeton et Révoquer tous les jetons sont enregistrées dans le journal d’audit de l’organisation sous org.api_token.create, org.api_token.revoke et org.api_secret.rotate.

Limite de requêtes

L’API accepte 60 requêtes par organisation et par minute. Cette limite est partagée entre les endpoints d’équipe, de domaine et de pages de paiement. Une requête qui dépasse la limite renvoie 429 avec le code d’erreur rate_limited. Réessayez avec une temporisation progressive au début de la minute suivante.

Créer une équipe

Utilisez POST /v1/teams/ pour créer une équipe dans l’organisation du jeton.

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

Le nom de l’équipe doit respecter les conditions suivantes :

• Contenir entre 3 et 32 caractères
• Utiliser des lettres, des chiffres, des traits de soulignement, des espaces ou des apostrophes
• Être unique au sein de l’organisation

Les traits d’union ne sont pas acceptés dans les noms d’équipe.

Une requête réussie renvoie 201 Created :

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

Enregistrez data.teamId. Vous en aurez besoin pour enregistrer ou supprimer des domaines pour l’équipe.

Un conflit renvoie 409 team_name_exists avec l’équipe existante : rappeler l’endpoint est donc sans risque et vous donne toujours un ID exploitable :

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

La création d’une équipe n’active pas l’intégration automatique des domaines. Cette fonction est configurée séparément pour chaque équipe et désactivée par défaut.

Enregistrer des domaines

Utilisez POST /v1/domains/ pour enregistrer entre 1 et 100 noms d’hôte de domaines gérés pour une équipe. team_id est obligatoire lorsque vous utilisez un jeton d’API d’organisation.

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"
    ]
  }'

Envoyez les noms d’hôte sans protocole, port, chemin, chaîne de requête ni fragment. cside supprime les espaces superflus et normalise les noms d’hôte acceptés en minuscules.

Chaque élément enregistre le nom d’hôte exact que vous envoyez. L’API ne crée pas de domaine avec joker. Incluez donc tous les noms d’hôte dont vous avez besoin, comme example.com et www.example.com.

L’endpoint renvoie 200 OK avec un résultat pour chaque valeur d’entrée, dans le même ordre :

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

La requête peut contenir des résultats valides et non valides tout en renvoyant 200 OK. Vérifiez chaque résultat :

Vous pouvez relancer sans risque la requête pour les domaines déjà créés pour la même équipe. Elle renvoie existing au lieu de créer un doublon. Un nom d’hôte géré par une autre équipe renvoie invalid avec domain_already_licensed.

Si les domaines ont été enregistrés mais que cside n’a pas pu terminer l’envoi de la configuration vers le réseau de diffusion, la requête renvoie 503 domain_registration_unavailable avec le message « Domains saved, but synchronization is incomplete. Retry to synchronize them. » Renvoyez la même requête : les noms d’hôte enregistrés reviennent avec l’état existing et la synchronisation est relancée.

Les nouveaux domaines bénéficient automatiquement de la protection gérée. Aucun appel d’API d’activation distinct n’est requis. La configuration peut prendre un peu de temps pour atteindre le réseau de diffusion.

Codes de validation des domaines

Un résultat invalid peut inclure l’un de ces codes :

Ajouter des pages de paiement

Utilisez POST /v1/payment-pages/ pour ajouter un sélecteur de page de paiement à une équipe existante. team_id est obligatoire lorsque vous utilisez un jeton d’API d’organisation. Il est facultatif pour un jeton limité à une équipe et, s’il est fourni, il doit correspondre à l’équipe du jeton.

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

Envoyez payment_page sous forme de sélecteur canonique hôte/chemin, sans https://, sans port et sans URL complète. Par exemple, utilisez checkout.example.com/checkout et non https://checkout.example.com/checkout. cside supprime les espaces superflus ainsi que les chaînes de requête et les barres obliques finales avant de stocker le sélecteur. Un fragment # est conservé tel qu’envoyé, afin que les applications monopages qui acheminent leur page de paiement par fragment puissent l’utiliser pour la correspondance. Un sélecteur qui contient des espaces, comme checkout.example.com/check out, est rejeté avec 400 invalid_payment_page.

Le sélecteur utilise le même format de motif que le tableau de bord. Une équipe peut avoir jusqu’à 500 sélecteurs de pages de paiement. L’endpoint n’enregistre pas de domaine ; enregistrez donc d’abord le nom d’hôte avec POST /v1/domains/ s’il n’est pas encore géré par l’équipe.

L’endpoint renvoie 200 OK :

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

Ajouter à nouveau le même sélecteur est sans risque et renvoie status: "existing". Un nouveau sélecteur renvoie status: "created". Lorsque l’équipe possède des domaines correspondants, cside met à jour leurs projections de pages de paiement et la configuration associée une fois le sélecteur au niveau de l’équipe stocké.

Charger cside pour l’équipe

Utilisez le teamId renvoyé lors de la création de l’équipe dans l’URL standard du script cside. Ne le remplacez pas par un domainId.

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

Le nom d’hôte de la page doit être enregistré auprès de l’équipe dont l’ID est utilisé dans l’URL du script. Si l’enregistrement est absent ou si l’équipe ne correspond pas, la requête renvoie 403. Si cela se produit immédiatement après l’enregistrement, réessayez un peu plus tard. Contactez le support cside si le problème persiste.

La surveillance standard ne nécessite ni enregistrement CNAME du client ni réacheminement du trafic. Si votre site applique une politique de sécurité du contenu restrictive, suivez le guide de configuration CSP pour autoriser *.csidetm.com.

Intégration automatique des domaines

L’intégration automatique des domaines est une fonction facultative de l’équipe pour les déploiements qui chargent le script d’amorçage cside standard. Elle est désactivée par défaut pour les nouvelles équipes. Contactez votre représentant cside si vous devez l’activer.

Lorsque cette fonction est activée et qu’un nom d’hôte non enregistré charge le script d’amorçage /client.js ou /script.js propre à l’équipe, cside transmet le nom d’hôte référent par le même flux de validation et d’enregistrement des domaines. Conservez l’attribut standard referrerpolicy="origin" pour rendre l’origine de la page disponible sans exposer son chemin ni sa chaîne de requête.

La requête qui détecte le nom d’hôte non enregistré n’est pas relancée. L’enregistrement s’applique à une requête de script ultérieure, après la propagation de la configuration. Les domaines enregistrés automatiquement apparaissent dans l’inventaire des domaines de l’équipe comme ceux enregistrés par l’API.

L’intégration automatique ne crée pas d’équipes et les requêtes vers d’autres endpoints cside n’enregistrent pas de nom d’hôte. Utilisez le flux d’API explicite lorsque vous avez besoin d’un résultat pour chaque domaine avant de déployer le script. L’intégration automatique s’applique au script de surveillance standard et n’active pas la collecte de données Device Intelligence.

Lister les équipes

Utilisez GET /v1/teams/ avec un jeton d’organisation. Les jetons limités à une équipe ne peuvent pas appeler cet endpoint. Omettez name pour lister les équipes, ou indiquez un nom exact et sensible à la casse. Les espaces aux extrémités sont supprimés, comme à la création. Des équipes renommées peuvent partager un nom : traitez toujours un tableau de résultats. Les équipes suspendues sont incluses. Sans correspondance, la réponse est 200 OK avec un tableau data vide.

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
}

Lister les domaines

Utilisez GET /v1/domains/ pour lister les domaines. Avec un jeton d’organisation, omettez team_id pour lire toute l’organisation ou indiquez une équipe. Un jeton d’équipe ne peut lire que sa propre équipe, même sans team_id. Une équipe inconnue ou inaccessible renvoie 404 team_not_found. Le filtre facultatif domain correspond à un nom d’hôte exact.

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
}

Les résultats incluent les domaines gérés et non gérés. id correspond au domainId renvoyé à l’enregistrement. Vérifiez managed avant d’utiliser cet ID avec DELETE /v1/domains/ : seuls les domaines gérés peuvent être supprimés par cette API. Sans nom d’hôte correspondant, data est vide.

Parcourir les résultats

Les deux endpoints acceptent limit (1 à 100, 50 par défaut) et un cursor facultatif. Les résultats sont classés par date de création, du plus ancien au plus récent, puis par ID en cas d’égalité. Chaque réponse 200 OK contient un tableau data et next_cursor. Continuez jusqu’à ce que next_cursor soit null.

Traitez le curseur comme une valeur opaque et encodez-le pour l’URL. Conservez la portée du jeton et les filtres entre les pages. Un curseur mal formé ou provenant d’une autre requête ou d’un autre compte renvoie 400 invalid_cursor ; relancez la requête sans curseur.

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"

Supprimer des domaines

Utilisez DELETE /v1/domains/ avec les valeurs domainId renvoyées lors de l’enregistrement des domaines. N’envoyez pas de noms d’hôte à cet 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"
    ]
  }'

Vous pouvez envoyer entre 1 et 100 ID de domaine. Une requête réussie renvoie des résultats partiels dans l’ordre :

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

La suppression est idempotente. Un ID inconnu, un domaine déjà supprimé ou un domaine extérieur à l’équipe cible renvoie not_found sans exposer d’informations sur une autre équipe.

Supprimer une équipe

Utilisez DELETE /v1/teams/ pour supprimer définitivement une équipe et tous ses domaines. La requête exige un jeton d’organisation avec Supprimer des équipes (teams:delete). Cette autorisation inclut la suppression des domaines ; domains:delete seul ne permet pas de supprimer une équipe. Générez un nouveau jeton pour ajouter cette autorisation à une intégration existante. Les jetons limités à une équipe ne sont pas acceptés.

Envoyez le teamId obtenu à la création de l’équipe dans team_id, sous forme de chaîne décimale entre guillemets. Il n’est pas nécessaire de lister ses domaines ni de les supprimer séparément.

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

Une requête réussie renvoie 200 OK. deletedDomains indique le nombre de domaines supprimés :

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

Une équipe avec un abonnement Stripe associé renvoie 409 team_subscription_attached. Résiliez l’abonnement avant de supprimer l’équipe. Si l’abonnement est déjà résilié et que l’erreur persiste, contactez le support cside.

Une équipe inconnue, appartenant à une autre organisation ou déjà supprimée renvoie 404 team_not_found. Répéter une suppression réussie ne supprime rien d’autre. Un échec du nettoyage renvoie 503 team_deletion_unavailable. Réessayez plus tard et contactez le support si l’erreur persiste.

L’accès Enterprise est vérifié à chaque requête. Si vous supprimez la dernière équipe Enterprise active de l’organisation, les requêtes suivantes à l’API publique, y compris les nouvelles tentatives, renvoient 403 enterprise_required.

Erreurs au niveau de la requête

Les échecs qui concernent toute la requête utilisent cette structure :

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

Liste de contrôle de sécurité

• Générez un jeton distinct et nommé pour chaque intégration backend
• Accordez uniquement les autorisations nécessaires à cette intégration
• Stockez les jetons dans un gestionnaire de secrets côté serveur
• N’exposez jamais les jetons dans le code du navigateur, les URL, le contrôle de version ou les journaux
• Révoquez immédiatement un jeton s’il est exposé ; utilisez Révoquer tous les jetons lorsque vous ne savez pas quel jeton a fuité ou que le jeton est antérieur à la liste des jetons
• Consultez la colonne Dernière utilisation et révoquez les jetons qui ne servent plus
• Traitez les ID d’équipe et de domaine renvoyés comme des chaînes

Documentation associée

• Référence interactive de l’API
• Ajouter votre domaine
• Ajouter le script cside
• Paramètres du tableau de bord