The BrandShelter SSL API with ACME support enables automated SSL certificate management through industry-standard workflows and offers you new ways to streamline certificate management and integrate it directly into your existing workflows.
Whether you're managing a single certificate or an extensive portfolio, the SSL API helps reduce manual effort and provides greater flexibility and control over the certificate lifecycle.
Only SSL certificates which are supported and managed by BrandShelter are accepted.
Introduction - Getting Started
What the SSL API Enables
BrandShelter’s SSL API supports the full lifecycle management of Domain Validation (DV), Organization Validation (OV), and Extended Validation (EV) certificates.
- Programmatic SSL certificate ordering and issuance on BrandShelter
- Certificate information and status retrieval for certificates managed on BrandShelter
- Automated renewals, reissuance, and revocation of certificates managed on BrandShelter
- Integration with customer systems and operational workflows
- Management of DV, OV, and EV certificate portfolios through a single API
ACME Support for Automated Certificate Management
BrandShelter’s SSL API now supports the ACME protocol, allowing customers to automate certificate management for supported DV certificate products using popular ACME-compatible clients such as:
- Certbot
- acme.sh
- lego
- win-acme
- Traefik
- Caddy
See below section: "Using ACME with BrandShelter > Step 2: Configure your ACME client" for more information.
DNS Validation
For customers using BrandShelter-managed DNS, validation records can be published automatically, helping simplify certificate issuance and renewal even further.
When ordering through the ACME endpoint any required DNS auth records are created automatically so there is no need to manually do that on BrandShelter or with the DNS API. The ACME orders do DNS edits/publications internally and don't use the DNS API themselves.
Why This Matters
As SSL certificate validity periods continue to decrease across the industry, organizations will need to renew and validate certificates more frequently. Automation is rapidly becoming an important requirement for IT, infrastructure, and security teams.
Get Started
Explore the SSL API and ACME documentation and implementation guide to learn how to start automating certificate management.
Introduction to the SSL API solution
Actions Supported in the SSL API
Action |
GraphQL operation |
|---|---|
List / filter / inspect certificates |
|
Order a new certificate |
|
Reissue a certificate |
|
Renew a certificate |
|
Edit metadata |
|
Revoke an active certificate |
|
Automated DV lifecycle |
ACME protocol (separate from GraphQL) |
List active certificates expiring this year
query ExpiringSoon {
sslCertificates(
state: [active],
expiresAtBefore: "2026-12-31T00:00:00Z",
first: 50
) {
nodes {
id
commonName
expiresAt
autoRenew
}
totalCount
}
}
Renew a certificate
Reuses the existing certificate's CSR, contacts, validation method and other attributes — only the certificate id needs to be supplied.
mutation RenewSSLCertificate {
renewSslCertificate(id: "1041") {
workRequest {
id
type
state
createdAt
}
}
}
Sample response (renewal accepted and submitted):
{
"data": {
"renewSslCertificate": {
"workRequest": {
"id": "8821",
"type": "RENEW_SSL_CERTIFICATE",
"state": "submitted",
"createdAt": "2026-05-28T09:42:11Z"
}
}
}
}
Renewal is allowed when the certificate is not of an "external" type (i.e. managed through BrandShelter, not merely imported for tracking) and is currently in state active or expired. Otherwise the mutation returns:
{
"errors": [
{
"message": "Certificate is not renewable",
"extensions": { "code": "certificate_not_renewable" }
}
],
"data": { "renewSslCertificate": null }
}
Revoke a certificate
Allowed when the product type permits revocation (see SSLCertificateType.revocable) and the certificate is currently in state active.
mutation RevokeSSLCertificate {
revokeSslCertificate(id: "1041") {
sslCertificateId
workRequestId
}
}
Sample response:
{
"data": {
"revokeSslCertificate": {
"sslCertificateId": "1041",
"workRequestId": "8822"
}
}
}
Best Practices
For ordered certificates, enrol in automatic renewal by passing
autoRenew: true— the platform will then track expiry and trigger renewals on the client's behalf.
For pure DV automation, prefer ACME over driving the GraphQL renew flow from a client. ACME is fully unattended once configured and integrates with standard tooling.
Before attempting reissue or revoke, check
SSLCertificateType.reissuable/.revocablefor the product type — these flags drive the allowed actions and the matching error codes.
For DigiCert and Sectigo products with vendor-mandated 199-day maximum lifetimes, no client action is required: the platform handles the auto-reissue cycle transparently, and clients see a normal 1-year renewal cadence.
When polling work-request status, back off exponentially. Avoid tight polling loops against the GraphQL endpoint.
Watch the certificate
statefor terminal failure states (order_failed,renewal_failed,reissue_failed) and surface them to operators promptly — they indicate a process that needs investigation.
Log mutation errors with their
extensions.codevalue (certificate_not_renewable,certificate_not_revocable, etc.) so support tooling can match on stable identifiers rather than message text.
Error Handling and Status Expectations
Certificate lifecycle states (SSLCertificateState enum):
Stable / terminal:
active,ordered,revoked,expired.In-flight (a work request is being processed):
renewal_pending,reissue_pending,revocation_pending.Terminal failures:
order_failed,renewal_failed,reissue_failed.Cancelled before completion:
order_cancelled,renewal_cancelled,reissue_cancelled.
Common mutation error codes (in extensions.code):
certificate_not_renewable— the certificate is of an "external" type, or is not currently in stateactiveorexpired.certificate_not_revocable— the certificate is not in stateactive, or the product type does not allow revocation.
Requesting an id that is not visible to the authenticated user, or that does not exist, returns a generic not-found / authorization error rather than disclosing whether the id exists.
For the full enum lists and field-level metadata, run a GraphQL introspection query against the live endpoint, or browse via a GraphQL client.
Using ACME with BrandShelter
BrandShelter supports the ACME protocol (RFC 8555) for ordering and renewing SSL certificates programmatically. Any standard ACME client — certbot, lego, acme.sh, win-acme, Traefik, Caddy — can point at BrandShelter and automate certificate issuance, while billing and contact data continue to flow through your existing BrandShelter account.
This documentation is for end users (customers) of BrandShelter who want to issue SSL certificates from their own infrastructure using an ACME client. No prior ACME knowledge is required.
What you get
Domain-validated (DV) certificates — single domain, multi-SAN, wildcard, and wildcard-SAN.
Billed against your BrandShelter account.
Automatic DCV publishing for managed zones — if BrandShelter manages your DNS, you don't need to do anything.
Drop-in replacement for any ACME client workflow you already have for Let's Encrypt or similar.
What is NOT supported
OV / EV certificates (organisation- or extended-validation).
Email-based domain validation.
HTTP-01 challenges. Only DNS-based validation is supported.
Code-signing certificates.
How it works at a glance
An ACME client communicates with the BrandShelter ACME server, which sits in front of the existing certificate ordering pipeline:
You generate an EAB credential (kid + HMAC key) in the BrandShelter UI. This binds an ACME account to your BrandShelter account so issued certificates are billed to you.
You configure your ACME client with the EAB credential and the BrandShelter ACME directory URL.
The client requests a certificate. BrandShelter publishes the DCV record automatically (for managed zones) or emails you the record to publish (for unmanaged zones).
Once validation completes, the client downloads the certificate.
Prerequisites
A BrandShelter account with at least one SSL-eligible contact (most accounts have one — see Configuring the SSL contact below if not).
An ACME client installed on the machine that will request and store certificates.
For each domain you want a certificate for, the ability to publish a CNAME record (only required for unmanaged zones — see Domain control validation).
Step 1: Generate an EAB credential
Sign in to BrandShelter.
Open the user menu (top right) and choose ACME Credentials.
Click New credential.
Enter a descriptive label (e.g. certbot on prod-web-1) and submit.
BrandShelter generates a
kid(key ID) and anHMAC key.
The HMAC key is shown only once. Copy both the kid and the HMAC key into your secrets store immediately. If you lose the HMAC key, revoke the credential and generate a new one.
Step 2: Configure your ACME client
The ACME directory URL is:
https://<your-brandshelter-host>/acme/directory<your-brandshelter-host> is either your white-labled custom host or secure.brandshelter.com.
Each ACME client has its own way of supplying EAB credentials. Examples for the most common clients:
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 writes to/etc/letsencryptand/var/log/letsencrypt, which are root-owned on most Linux distros. The alternative is to point--config-dir,--logs-dir, and--work-dirat writable paths.--manual --manual-auth-hook /bin/true— without an authenticator flag, certbot prompts you to pick one ofapache/dns-cloudflare/standalone/webroot. None of those apply to BrandShelter, because the ACME DNS-01 challenge is a no-op gate on our side: it succeeds as soon as your client confirms it. Pointing the auth hook at/bin/truetells certbot "the record has been published" without actually publishing anything. The record that actually validates the domain is the Sectigo CNAME — see Domain control validation below.--email/--agree-tos— pre-answers the two interactive prompts on first run. Drop them if you'd rather be prompted.
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
The --dns=<provider> flag is only required if you want lego to publish the ACME DNS-01 TXT record. For BrandShelter that record is a no-op (see the certbot section above). If you'd rather not wire up a real DNS provider, use --dns=manual with a stub command that exits 0 — the actual DCV record is the Sectigo CNAME described in Domain control validation.
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
As with lego, --dns <provider> is only used to publish the ACME DNS-01 TXT record, which BrandShelter ignores. You can use --dns dns_manual_mode and press Enter at the prompt, or wire up a stub dnsapi if you want renewals to run unattended.
Caddy / Traefik / other clients
Set the directory URL to https://<your-brandshelter-host>/acme/directory and provide the kid and HMAC key according to your client's documentation. Any RFC 8555 client that supports External Account Binding will work.
Step 3: Your ACME client creates an ACME account on first run
On the first request, the client generates its own account key locally (never sent to BrandShelter) and registers it via the newAccount endpoint using your EAB credential. This step is automatic — you don't see it. From then on, all requests from that client are authenticated with the locally generated key.
The EAB credential is consumed by the first newAccount call. It can only be bound to one ACME account. If you need a second client, generate a second EAB credential.
Domain control validation (DCV)
Two records, only one matters. ACME clients commonly display a prompt like "Please deploy a DNS TXT record under
_acme-challenge.example.com... ". With BrandShelter that record is a no-op — see the client-specific examples in Step 2 for how to skip it. The record that actually validates the domain is the Sectigo CNAME described below.
BrandShelter performs DCV through CNR/Sectigo, not through the ACME DNS-01 challenge. The DNS record you (or BrandShelter) need to publish is the standard Sectigo CNAME, not the _acme-challenge TXT record that Let's Encrypt uses.
Managed zones (DNS hosted by BrandShelter)
Nothing for you to do. BrandShelter publishes the CNAME automatically, your ACME client polls the order, and once Sectigo validates the domain, the certificate becomes available.
Unmanaged zones (DNS hosted elsewhere)
When you submit the order, BrandShelter sends an email to the contacts configured on your BrandShelter account and to the contact addresses your ACME client supplied in the
newAccountrequest. The email contains the DNS record(s) to publish.Publish the CNAME at your DNS provider.
Your ACME client continues polling the order; it stays in
processinguntil Sectigo confirms the record is live.Once validated, the certificate is issued and the client downloads it.
Validation can take up to 5–10 minutes once the record is published, depending on DNS propagation. Some ACME clients will retry polling automatically; others may time out — re-run the client if so.
Configuring the SSL contact (optional)
SSL certificates require a contact record (name, address, etc.) for the certificate's WHOIS-equivalent metadata. BrandShelter automatically picks the first SSL-eligible contact on your account.
The Configure button appears next to a credential only after it has been used at least once. The SSL contact is stored on the ACME account that gets created on the first newAccount call (see Step 3), so until your client has made that first call there is no ACME account to attach the contact to.
If you want a specific contact used instead:
Go to User menu → ACME Credentials.
Click Configure next to the credential.
Search and select the contact you want used for certificates issued via this credential.
The same contact is used for all four certificate roles (owner, admin, technical, billing).
Renewal
Renewal is automatic in the sense that every ACME client schedules renewals on its own. There is no "renew" endpoint in ACME — the client simply requests a new certificate before the old one expires. BrandShelter treats each request as a fresh order and bills accordingly.
For certbot, running certbot renew on a daily cron is sufficient. certbot renew re-uses the flags from the original certonly invocation, so make sure the first run used --non-interactive together with --email, --agree-tos, and --manual-auth-hook /bin/true — otherwise the cron renewal will stall waiting for the email / TOS / TXT-record prompts.
Revocation
Most ACME clients can revoke a certificate with a one-line command, for example:
certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem
BrandShelter supports both RFC 8555 authorisation modes: by ACME account key or by the certificate's own private key.
Limits and quotas
IP rate limit: 60 requests per minute per source IP.
Per-account rate limit: 20 requests per minute per ACME account.
If you hit a limit, the server responds with HTTP 429 and a Retry-After header — your client should back off automatically.
Managing your credentials
The ACME Credentials screen lists every credential on your account with:
The label you assigned, and the
kid.Creation and last-used timestamps.
The currently configured SSL contact (or "Auto").
Status (Active / Revoked).
To revoke a credential (e.g. you're decommissioning a server), click Revoke. This:
Immediately prevents the credential from being used in further
newAccountrequests.Deactivates the ACME account bound to it — existing ACME accounts using that credential will no longer be able to issue new certificates.
Does not revoke certificates already issued. Use the ACME revoke flow above for that.
Troubleshooting
"externalAccountBinding is required"
Your client is hitting newAccount without an EAB. Double-check the --eab-kid / --eab-hmac-key arguments (or equivalent for your client) are being passed.
"unauthorized" on newAccount
Most common causes:
HMAC key was copied with a leading/trailing whitespace.
The EAB credential has already been bound to an ACME account (each credential is single-use).
The EAB credential was revoked.
Order stuck in processing
For unmanaged zones, your DNS record probably isn't live yet or hasn't propagated. Verify with dig from a public resolver. For managed zones, contact BrandShelter support.
"rejectedIdentifier"
The combination of domains in your request isn't supported by the certificate type matched (e.g. wildcard requested but only single-domain product available). Contact your account manager to enable the right SSL product on the account.
Security notes
The HMAC key is the sole credential that lets a client claim certificates under your account. Treat it like an API token: store in a secrets manager, never commit to git, rotate (revoke + recreate) on suspected leak.
The ACME account key itself lives on the client machine and never leaves it. Losing the machine effectively requires generating a new EAB credential and re-registering.
BrandShelter encrypts the HMAC key at rest in addition to AWS RDS at-rest encryption.
Getting help
If you run into anything not covered here, please contact your BrandShelter account manager or support team with:
The ACME client and version you're using.
The exact command/configuration (with the HMAC key redacted).
The relevant ACME server response (the
type,status, anddetailfields are most useful).