API REST publique | cside docs

Utilisez l’API REST publique de cside pour provisionner des équipes et des domaines gérés depuis un flux de travail backend. L’API utilise JSON sur HTTPS et un jeton Bearer associé à l’organisation.

Référence interactive de l’API

Utilisez la référence interactive de l’API pour consulter les schémas actuels des requêtes et des réponses. Le document OpenAPI est disponible pour générer du code.

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 :

Créez un jeton d’API d’organisation avec les autorisations requises
Appelez POST /v1/teams/ et enregistrez le teamId renvoyé
Appelez POST /v1/domains/ avec ce teamId et jusqu’à 100 noms d’hôte
Vérifiez chaque élément de data.results 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

Forfait Enterprise requis

L’API publique est disponible pour les organisations qui disposent d’une équipe Enterprise active. Contactez l’équipe commerciale si vous avez besoin d’un accès à l’API.

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 uniquement les autorisations dont l’intégration a besoin :

Autorisation	Accès à l’API
Créer des équipes (`teams:create`)	`POST /v1/teams/`
Enregistrer des domaines (`domains:create`)	`POST /v1/domains/`
Supprimer des domaines (`domains:delete`)	`DELETE /v1/domains/`

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.

Envoyez le jeton avec chaque requête :

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Les jetons restent valides jusqu’à ce qu’un administrateur sélectionne Révoquer tous les jetons. Cette action invalide immédiatement tous les jetons d’API de l’organisation.

Conservez les ID sous forme de chaînes

Envoyez team_id et les ID de domaine sous forme de chaînes décimales entre guillemets dans JSON. Ne les convertissez pas en nombres JavaScript.

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 et de domaine. 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.

La création d’une équipe n’est pas idempotente

L’endpoint n’accepte pas de clé d’idempotence. La réutilisation d’un nom d’équipe renvoie 409 team_name_exists sans renvoyer l’ID de l’équipe existante. Enregistrez la réponse réussie avant de commencer l’enregistrement des domaines.

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 :

État	Signification
`created`	cside a enregistré le nom d’hôte et renvoyé son nouveau `domainId`
`existing`	La même équipe possède déjà le nom d’hôte et le `domainId` d’origine est renvoyé
`invalid`	cside n’a pas enregistré le nom d’hôte, consultez `code` et `message`

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.

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 :

Code	Signification
`empty_domain`	La valeur d’entrée est vide
`invalid_domain`	Le nom d’hôte n’est pas valide
`public_suffix_domain`	La valeur d’entrée est un suffixe public et non un nom d’hôte enregistrable
`internal_domain`	Le nom d’hôte est réservé ou non autorisé
`reserved_ip`	DNS résout le nom d’hôte vers une adresse IP réservée
`wildcard_conflict`	Un domaine avec joker existant couvre déjà ce nom d’hôte
`subdomain_conflict`	Une configuration de domaine existante inclut déjà ce sous-domaine
`domain_already_licensed`	Une autre équipe gère déjà le nom d’hôte
`internal_error`	cside n’a pas pu valider ou créer le domaine

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.

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.

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

Statut HTTP	Codes d’erreur courants	Action
`400`	`invalid_request`	Vérifiez le corps JSON, les champs obligatoires, les chaînes d’ID et les limites d’éléments
`401`	`unauthorized`	Vérifiez le jeton Bearer et si tous les jetons de l’organisation ont été révoqués
`403`	`insufficient_scope`, `enterprise_required`, erreurs de suspension	Vérifiez les autorisations du jeton, l’accès au forfait et le statut du compte
`404`	`team_not_found`	Confirmez que l’ID de l’équipe appartient à l’organisation du jeton
`409`	`team_name_exists`	Choisissez un nom d’équipe unique ou utilisez l’équipe existante
`429`	`rate_limited`	Réessayez avec une temporisation progressive après la fenêtre de limite actuelle
`503`	`rate_limit_unavailable`, `domain_deletion_unavailable`	Réessayez plus tard et contactez le support cside si l’erreur persiste

Liste de contrôle de sécurité

Générez un jeton distinct 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 tous les jetons de l’organisation si l’un d’eux est exposé
Traitez les ID d’équipe et de domaine renvoyés comme des chaînes