API SSL

Lister les certificats actifs expirant cette année

query ExpiringSoon {
  sslCertificates(
    state: [active],
    expiresAtBefore: "2026-12-31T00:00:00Z",
    first: 50
  ) {
    nodes {
      id
      commonName
      expiresAt
      autoRenew
    }
    totalCount
  }
}

Renouveler un certificat

Réutilise la CSR existante, les contacts, la méthode de validation et les autres attributs du certificat existant ; seul l'identifiant du certificat (Certificate ID) doit être fourni.

mutation RenewSSLCertificate {
  renewSslCertificate(id: "1041") {
    workRequest {
      id
      type
      state
      createdAt
    }
  }
}

Exemple de réponse (renouvellement accepté et soumis) :

{
  "data": {
    "renewSslCertificate": {
      "workRequest": {
        "id": "8821",
        "type": "RENEW_SSL_CERTIFICATE",
        "state": "submitted",
        "createdAt": "2026-05-28T09:42:11Z"
      }
    }
  }
}

Le renouvellement est autorisé lorsque le certificat n'est pas de type « externe » (c'est-à-dire géré via BrandShelter, et non simplement importé à des fins de suivi) et qu'il se trouve actuellement dans l'état active (actif) ou expired (expiré). Sinon, la mutation renvoie :

{
  "errors": [
    {
      "message": "Certificate is not renewable",
      "extensions": { "code": "certificate_not_renewable" }
    }
  ],
  "data": { "renewSslCertificate": null }
}

Révoquer un certificat

Autorisé lorsque le type de produit permet la révocation (voir SSLCertificateType.revocable) et le certificat est actuellement dans le statut active(actif).

mutation RevokeSSLCertificate {
  revokeSslCertificate(id: "1041") {
    sslCertificateId
    workRequestId
  }
}

Exemple de réponse :

{
  "data": {
    "revokeSslCertificate": {
      "sslCertificateId": "1041",
      "workRequestId": "8822"
    }
  }
}

Best Practices - Meilleures pratiques

• Pour les certificats commandés, optez pour le renouvellement automatique en sélectionnant autoRenew: true — la plateforme assurera ensuite le suivi des échéances et déclenchera automatiquement les renouvellements.
   

• Pour une automatisation purement basée sur la validation de domaine (DV), privilégiez ACME plutôt que de piloter le flux de renouvellement GraphQL depuis un client. Une fois configuré, ACME fonctionne de manière totalement autonome et s'intègre aux outils standards.
   

• Avant de tenter une réémission ou une révocation, vérifiez SSLCertificateType.reissuable / .revocable pour le type de produit — ces indicateurs déterminent les actions autorisées ainsi que les codes d'erreur correspondants.
   

• Pour les produits DigiCert et Sectigo soumis à une durée de vie maximale de 199 jours imposée par le fournisseur, aucune intervention n'est requise : la plateforme gère le cycle de réémission automatique en toute transparence, et vous bénéficiez d'un rythme de renouvellement standard d'un an.
   

• Lors de l'interrogation du statut d'une demande de travail, appliquez un espacement exponentiel. Évitez les boucles d'interrogation à haute fréquence vers le point de terminaison GraphQL.
   

• Vérifiez le statut du certificat - state - pour les états finaux en échec (order_failed, renewal_failed, reissue_failed) et les transmettre rapidement aux opérateurs — ils indiquent un processus qui nécessite une enquête.
   

• Enregistrez les erreurs de mutation avec leur valeur extensions.code  (certificate_not_renewable, certificate_not_revocable, etc.) afin que les outils d'assistance puissent effectuer des correspondances sur la base d'identifiants stables plutôt que sur le texte du message.

Gestion des erreurs et statuts

Statuts du cycle de vie des certificats (SSLCertificateState enum) :

• Stable / final : active, ordered, revoked, expired.

• En cours (une demande d'opération (work request) est en cours de traitement) : renewal_pending, reissue_pending, revocation_pending.

• Echecs finaux : order_failed, renewal_failed, reissue_failed.

• Annulé avant finalisation : order_cancelled, renewal_cancelled, reissue_cancelled.

Codes d'erreur de mutation courants (dans extensions.code) :

• certificate_not_renewable (certificat non renouvelable) — le certificat est de type « externe » ou n'est pas actuellement dans un statut active (actif) ou expired (expiré).

• certificate_not_revocable (certificat non révocable) — le certificat n'est pas en statut active (actif), ou le type de produit ne permet pas la révocation.

La demande d'un identifiant (ID) invisible pour l'utilisateur authentifié, ou inexistant, renvoie une erreur générique de type « non trouvé » ou « autorisation refusée » plutôt que de révéler si l'identifiant existe.

Pour obtenir les listes complètes des énumérations et les métadonnées au niveau des champs, exécutez une requête d'introspection GraphQL sur le point de terminaison actif ou parcourez-les via un client GraphQL.