L’API SSL de BrandShelter avec prise en charge du protocole ACME vous offre de nouvelles possibilités pour simplifier la gestion des certificats et l’intégrer directement à vos processus et workflows existants.
Que vous gériez un seul certificat ou un portefeuille important, l’API SSL permet d'optimiser la gestion de vos certificats BrandShelter et de réduire les tâches manuelles tout en offrant davantage de flexibilité et de contrôle sur l’ensemble du cycle de vie des certificats.
Seuls les certificats SSL pris en charge et gérés par BrandShelter sont acceptés.
Introduction et Premiers pas
Ce que vous pouvez faire avec l’API SSL
- Commander et émettre des certificats SSL par programmation sur BrandShelter
- Consulter les informations et le statut des certificats gérés sur BrandShelter
- Automatiser les renouvellements et les révocations des certificats gérés sur BrandShelter
- Intégrer la gestion des certificats à vos systèmes et workflows existants
- Gérer les certificats DV, OV et EV via une API unique
- Prise en charge d’ACME pour vos workflows existants
ACME
Nous prenons désormais également en charge le protocole ACME, vous permettant d’automatiser la gestion des certificats à l’aide de clients ACME populaires tels que :
- Certbot
- acme.sh
- lego
- win-acme
- Traefik
- Caddy
Voir plus bas : "Utilisation d'ACME avec BrandShelter > Étape 2 : Configurez votre client ACME" pour plus d'informations.
DNS
Pour les clients utilisant le DNS géré par BrandShelter, les enregistrements de validation peuvent être publiés automatiquement, simplifiant davantage l’émission et le renouvellement des certificats.
Lors d'une commande via notre client ACME, les enregistrements d'authentification DNS nécessaires sont créés automatiquement ; il n'est donc pas nécessaire d'effectuer cette opération manuellement sur BrandShelter ou via l'API DNS. Les commandes ACME gèrent les modifications et publications DNS en interne et n'utilisent pas directement l'API DNS.
Pourquoi est-ce important ?
Alors que la durée de validité des certificats continue de diminuer dans l’ensemble du secteur, les organisations devront renouveler et valider leurs certificats plus fréquemment. L’automatisation permet de réduire la charge opérationnelle, d’améliorer l’efficacité et de simplifier la gestion des certificats face à ces évolutions.
Commencer avec l'API SSL
Consultez la documentation de l’API SSL ainsi que le guide d’implémentation ACME pour découvrir comment automatiser la gestion de vos certificats.
Consulter le guide de l’API SSL (uniquement disponible en Anglais)
Présentation de la solution API SSL
Actions prises en charge par l'API SSL
Action |
Operation GraphQL |
|---|---|
Lister / filtrer / examiner les certificats |
|
Commander un nouveau certificat |
|
Réémettre un certificat |
|
Renouveler un certificat |
|
Modifier les métadonnées |
|
Révoquer un certificat actif |
|
DV cycle de vie automatisé |
ACME protocol (distinct de GraphQL) |
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/.revocablepour 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 statutactive(actif) ouexpired(expiré).certificate_not_revocable(certificat non révocable) — le certificat n'est pas en statutactive(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.
Utilisation d'ACME avec BrandShelter
BrandShelter prend en charge le protocole ACME (RFC 8555) pour la commande et le renouvellement automatisés de certificats SSL. Tout client ACME standard — certbot, lego, acme.sh, win-acme, Traefik, Caddy — peut interagir avec BrandShelter pour automatiser l'émission de certificats, tout en maintenant la facturation et la gestion des contacts via votre compte BrandShelter.
Cette documentation s'adresse aux utilisateurs finaux (clients) de BrandShelter souhaitant émettre des certificats SSL depuis leur propre infrastructure à l'aide d'un client ACME. Aucune connaissance préalable d'ACME n'est requise.
Ce qui est inclus
Certificats à validation de domaine (DV) — domaine unique, multi-SAN, générique (wildcard) et générique-SAN (wildcard-SAN).
Facturation automatique sur votre compte BrandShelter.
Publication automatique des DCV pour les zones gérées — si BrandShelter gère votre DNS, vous n'avez rien à faire.
Solution de remplacement directe pour tout flux de travail client ACME que vous utilisez déjà pour Let's Encrypt ou un service similaire.
Ce qui n'est PAS pris en charge
Certificats OV / EV (validation d'organisation ou étendue).
Validation de domaine par e-mail.
Défis HTTP-01. Seule la validation DNS est prise en charge.
Certificats de signature de code.
Comment ça fonctionne en bref
Un client ACME communique avec le serveur ACME de BrandShelter, qui se situe en amont du pipeline de commande de certificats existant :
Vous générez des identifiants d'authentification EAB (identifiant KID + clé HMAC) dans l'interface utilisateur de BrandShelter. Cela associe un compte ACME à votre compte BrandShelter afin que les certificats émis vous soient directement et automatiquement facturés.
Vous configurez votre client ACME avec les informations d'identification EAB et l'URL du répertoire ACME de BrandShelter.
Le client demande un certificat. BrandShelter publie automatiquement l'enregistrement DCV (pour les zones gérées) ou vous l'envoie par courriel pour publication (pour les zones non gérées).
Une fois la validation terminée, le client télécharge le certificat.
Prérequis
Un compte BrandShelter avec au moins un contact éligible SSL (la plupart des comptes en ont un — voir Configuration du contact SSL ci-dessous si ce n'est pas le cas).
Un client ACME installé sur la machine qui demandera et stockera les certificats.
Pour chaque domaine pour lequel vous souhaitez un certificat, la possibilité de publier un enregistrement CNAME (uniquement requis pour les zones non gérées — voir Validation du contrôle de domaine ).
Étape 1 : Générer un identifiant EAB
Connectez-vous à BrandShelter.
Ouvrez le menu utilisateur (en haut à droite) et choisissez Identifiants ACME .
Cliquez sur Nouvelles informations d'identification .
Saisissez une étiquette descriptive (par exemple certbot sur prod-web-1 ) et soumettez.
BrandShelter génère un
kid(identifiant clé) et unHMAC key.
La clé HMAC n'est affichée qu'une seule fois. Copiez immédiatement l'identifiant et la clé HMAC dans votre gestionnaire de secrets. Si vous perdez la clé HMAC, révoquez l'identifiant et générez-en un nouveau.
Étape 2 : Configurez votre client ACME
L' URL du répertoire ACME est :
https://<your-brandshelter-host>/acme/directory<your-brandshelter-host> est soit votre hôte personnalisé en marque blanche, soit secure.brandshelter.com.
Chaque client d'ACME a sa propre méthode pour fournir les identifiants EAB.
Exemples pour les clients les plus courants :
certbot
sudo certbot certonly \ --server https://<your-brandshelter-host>/acme/directory \ --eab-kid <kid> \ --eab-hmac-key <hmac_key> \ --email you@example.com \ --agree-tos \ --preferred-challenges dns \ --manual \ --manual-auth-hook /bin/true \ -d example.com -d www.example.com
For wildcards:
sudo certbot certonly \ --server https://<your-brandshelter-host>/acme/directory \ --eab-kid <kid> \ --eab-hmac-key <hmac_key> \ --email you@example.com \ --agree-tos \ --preferred-challenges dns \ --manual \ --manual-auth-hook /bin/true \ -d "*.example.com" -d example.com
Why sudo, --manual, and --manual-auth-hook /bin/true ?
sudo— certbot écrit dans les répertoires/etc/letsencryptet/var/log/letsencrypt, qui appartiennent à l'utilisateur root sur la plupart des distributions Linux. L'alternative consiste à spécifier des chemins d'accès en écriture pour--config-dir,--logs-dir, et--work-dir.--manual --manual-auth-hook /bin/trueSans indicateur d'authentificateur, certbot vous invite à en choisir un parmi les options suivantes :apache/dns-cloudflare/standalone/webroot. Aucune ne s'applique à BrandShelter, car le défi ACME DNS-01 est une étape sans effet de notre côté : il réussit dès que votre client le confirme. Configurer le hook d'authentification/bin/trueindique à certbot que « l'enregistrement a été publié » sans pour autant publier quoi que ce soit. L'enregistrement qui valide réellement le domaine est le CNAME Sectigo (voir la section « Validation du contrôle de domaine » ci-dessous).--email/--agree-tos— Pré-répond aux deux questions interactives lors de la première exécution. Supprimez-les si vous préférez être invité à répondre.
lego
lego \ --server=https://<your-brandshelter-host>/acme/directory \ --email=ops@example.com \ --eab --kid=<kid> --hmac=<hmac_key> \ --domains=example.com --domains=www.example.com \ --dns=<your-dns-provider> \ run
L'option --dns=<provider> n'est requise que si vous souhaitez que Lego publie l'enregistrement TXT ACME DNS-01. Pour BrandShelter, cet enregistrement est sans effet (voir la section certbot ci-dessus). Si vous préférez ne pas configurer de fournisseur DNS réel, utilisez --dns=manualune commande factice qui renvoie 0 ; l'enregistrement DCV réel est le CNAME Sectigo décrit dans la section Validation du contrôle de domaine.
acme.sh
acme.sh --server https://<your-brandshelter-host>/acme/directory \ --register-account \ --eab-kid <kid> \ --eab-hmac-key <hmac_key> acme.sh --issue --dns <your-dns-provider> -d example.com -d www.example.com
Comme pour les Lego, --dns <provider>cette commande sert uniquement à publier l'enregistrement TXT ACME DNS-01, que BrandShelter ignore. Vous pouvez utiliser --dns dns_manual_mode et appuyer sur "Entrer" à l'invite, ou configurer un stub dnsapisi vous souhaitez que les renouvellements s'effectuent automatiquement.
Caddy / Traefik / autres clients
Configurez l'URL du répertoire https://<your-brandshelter-host>/acme/directoryet fournissez le kid (fichier enfant) et la clé HMAC conformément à la documentation de votre client. Tout client RFC 8555 prenant en charge la liaison de compte externe fonctionnera.
Étape 3 : Votre client ACME crée un compte ACME lors de sa première exécution
Lors de la première requête, le client génère localement sa propre clé de compte (jamais envoyée à BrandShelter) et l'enregistre via le point de terminaison newAccount à l'aide de vos identifiants EAB. Cette étape est automatique et transparente pour vous. Dès lors, toutes les requêtes provenant de ce client sont authentifiées avec la clé générée localement.
L'identifiant EAB est utilisé lors du premier appel newAccount. Il ne peut être associé qu'à un seul compte ACME. Si vous avez besoin d'un deuxième client, générez un deuxième identifiant EAB.
Validation du contrôle de domaine (DCV)
Deux enregistrements, mais un seul est requis. Les clients ACME affichent généralement un message du type « Veuillez déployer un enregistrement TXT DNS sous _acme-challenge.example.com … ». Avec BrandShelter, cet enregistrement est inopérant et sans effet ; consultez les exemples spécifiques au client à l’Etape 2 pour savoir comment l’ignorer. L’enregistrement qui valide réellement le domaine est le CNAME Sectigo décrit ci-dessous.
BrandShelter effectue la validation croisée (DCV) via CNR/Sectigo, et non via le défi ACME DNS-01. L'enregistrement DNS que vous (ou BrandShelter) devez publier est l'enregistrement CNAME standard de Sectigo, et non l'enregistrement TXT _acme-challenge utilisé par Let's Encrypt.
Zones gérées (DNS hébergé par BrandShelter)
Vous n'avez rien à faire. BrandShelter publie automatiquement l'enregistrement CNAME, votre client ACME vérifie la commande et, une fois que Sectigo a validé le domaine, le certificat est disponible.
Zones non gérées (DNS hébergé ailleurs, sur des NS externes à BrandShelter)
Lorsque vous soumettez la commande, BrandShelter envoie un courriel aux contacts configurés dans votre compte BrandShelter et aux adresses de contact fournies par votre client ACME dans la requête
newAccount. Ce courriel contient les enregistrements DNS à publier.Publiez l'enregistrement CNAME auprès de votre fournisseur DNS.
Votre client ACME continue d'interroger la commande ; il reste actif en statut
processingjusqu'à ce que Sectigo confirme que l'enregistrement est en ligne.Une fois validé, le certificat est émis et le client le télécharge.
La validation peut prendre de 5 à 10 minutes après la publication de l'enregistrement, selon la propagation DNS. Certains clients ACME réessaient automatiquement d'interroger la commande ; d'autres peuvent expirer — dans ce cas, relancez le client.
Configuration du contact SSL (facultatif)
Les certificats SSL nécessitent un enregistrement de contact (nom, adresse, etc.) pour les métadonnées équivalentes à celles du WHOIS. BrandShelter sélectionne automatiquement le premier contact éligible SSL de votre compte.
Le bouton Configure apparaît à côté d'une authentification uniquement après sa première utilisation. Le contact SSL est enregistré sur le compte ACME créé lors du premier appel newAccount (voir Etape 3). Par conséquent, tant que votre client n'a pas effectué ce premier appel, aucun compte ACME n'est créé pour y associer le contact.
Si vous souhaitez qu'un contact spécifique soit utilisé à la place :
Accédez au menu Utilisateur (Paramètres du compte) → Identifiants ACME (droits requis).
Cliquez sur Configurer à côté des informations d'identification.
Recherchez et sélectionnez le contact que vous souhaitez utiliser pour les certificats émis via cette authentification.
Le même contact est utilisé pour les quatre rôles liés au certificat (propriétaire, administrateur, technique, facturation).
Renouvellement
Le renouvellement est automatique : chaque client ACME le planifie et l'exécute lui-même. Il n’existe pas de terminal de renouvellement dédié dans ACME ; le client demande simplement un nouveau certificat avant l’expiration de l’ancien. BrandShelter traite chaque demande comme une nouvelle commande et facture en conséquence.
Pour certbot, une exécution quotidienne de la commande certbot renew via cron suffit. certbot renew réutilise les options de l'appel certonly initial ; assurez-vous donc que la première exécution utilise bien les options --non-interactive avec --email, --agree-tos, et --manual-auth-hook /bin/true — sinon le renouvellement cron restera bloqué en attente des invites par e-mail / TOS / enregistrement TXT.
Révocation
La plupart des clients ACME peuvent révoquer un certificat à l'aide d'une simple commande, par exemple :
certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem
BrandShelter prend en charge les deux modes d'autorisation RFC 8555 : par clé de compte ACME ou par la clé privée propre au certificat.
Limites et quotas
Limite de débit IP : 60 requêtes par minute et par adresse IP source.
Limite de débit par compte : 20 requêtes par minute par compte ACME.
Si vous atteignez une limite, le serveur répond avec HTTP 429 et un en-tête Retry-After ; votre client devrait alors automatiquement se retirer et faire marche arrière.
Gestion de vos identifiants
L' écran « Identifiants ACME » répertorie tous les identifiants de votre compte, notamment :
L'étiquette que vous avez attribuée, et le
kid.Horodatage de création et de dernière utilisation.
Le contact SSL actuellement configuré (ou « Auto »).
Statut (Actif / Révoqué).
Pour révoquer une authentification (par exemple, lors de la mise hors service d'un serveur), cliquez sur Révoquer. Cela :
Empêche immédiatement l'utilisation de ces informations d'identification pour des nouvelles requêtes ultérieures
newAccount.Désactive le compte ACME qui y est lié — les comptes ACME existants utilisant ces informations d'identification ne pourront plus émettre de nouveaux certificats.
Ne révoque pas les certificats déjà émis. Utilisez la procédure de révocation ACME décrite ci-dessus à cet effet.
Troubleshooting
"externalAccountBinding is required" ("externalAccountBinding est requis")
Votre client effectue des requêtes newAccount sans EAB. Vérifiez que les arguments --eab-kid / --eab-hmac-key (ou leur équivalent pour votre client) sont bien transmis.
"unauthorized" on newAccount (« non autorisé » sur newAccount)
Causes les plus fréquentes :
La clé HMAC a été copiée avec des espaces blancs en début et en fin de chaîne.
L'identifiant EAB a déjà été lié à un compte ACME (chaque identifiant est à usage unique).
L'accréditation EAB a été révoquée.
Commande bloquée en processing
Pour les zones non gérées, votre enregistrement DNS n'est probablement pas encore actif ou n'a pas été propagé. Vérifiez-le avec un dig auprès d'un résolveur DNS public. Pour les zones gérées, contactez l'assistance BrandShelter.
"rejectedIdentifier" ("identifiant rejeté")
La combinaison de domaines demandée n'est pas prise en charge par le type de certificat correspondant (par exemple, un certificat générique a été demandé, mais seul un certificat pour un seul domaine est disponible). Veuillez contacter votre gestionnaire / chargé(e) de compte BrandShelter pour activer le certificat SSL approprié.
Notes de sécurité
La clé HMAC est le seul identifiant permettant à un client de revendiquer des certificats sur votre compte. Traitez-la comme un jeton d'API : stockez-la dans un gestionnaire de secrets, ne l'enregistrez jamais dans Git et effectuez une rotation (révocation et recréation) en cas de suspicion de fuite.
La clé de compte ACME réside sur la machine cliente et n'en sort jamais. En cas de perte de cette machine, il est nécessaire de générer de nouvelles informations d'identification EAB et de se réinscrire.
BrandShelter chiffre la clé HMAC au repos en plus du chiffrement au repos d'AWS RDS.
Obtenir de l'aide et une assistance
Si vous rencontrez un problème non abordé ici, veuillez contacter votre chargé(e) de compte si vous en avez un ou l'équipe support BrandShelter, et renseignez les éléments suivants :
Le client ACME et la version que vous utilisez.
La commande/configuration exacte (avec la clé HMAC masquée).
La réponse pertinente du serveur ACME (les champs
type,status, etdetailsont les plus utiles).