Issuing a certificate

Issuance is asynchronous. POST /v1/certificates answers 202 with the certificate in pending and an empty challenges list — the challenges are planned by the issuance workflow just after the row is created, not by the call that created it.

Create the certificate

Console
API

Go to Certificates and choose Create Certificate. Give it a Name, add each Domain, and leave the source on Auto-issue via DNS challenge.The certificate lands in the list straight away, and the detail page shows Configure DNS to complete certificate issuance with the records to publish.

POST https://certificate.sa-saopaulo-1.basaltic.sh/v1/certificates
{
  "name": "prod-frontend",
  "domains": ["example.com", "www.example.com"]
}

name is unique per account and lands in the CRN, so it has to be URL-safe — letters, digits, dot, dash, underscore.

Poll until the challenges appear

GET /v1/certificates/{certificate_id}

The status moves to pending_dns and challenges grows one entry per domain, each carrying cname_record_name, expected_cname and our_dns.

Do not read challenges from the create response — it is always empty there. Poll the certificate.

Publish the CNAME

Each challenge needs _acme-challenge.<domain> pointing at that challenge’s expected_cname. Whether you do anything here depends on who hosts the zone — see below.

Wait for active

Each challenge flips verified: true as its CNAME resolves. Once every challenge is verified and signing completes, the certificate becomes active and certificate_pem, fingerprint, issued_at and expires_at are populated.

Who publishes the CNAME

Domain on Basaltic DNS
Domain hosted elsewhere

The challenge comes back with our_dns: true and the CNAME has already been created for you. There is nothing to do but poll until verified turns true.

The challenge comes back with our_dns: false. Add the record at your registrar, exactly as the challenge names it:

_acme-challenge.example.com.  CNAME  <expected_cname>

Take expected_cname from the challenge rather than copying it from anywhere else — it is per-order, and the target is where the validation TXT gets published during issuance.

The delegation is one-time work per domain, not per issuance. Leave the CNAME in place and renewals validate without you touching DNS again.

Wildcards

A wildcard SAN validates at its parent name, not at the literal SAN — this is RFC 8555 §8.4. So a certificate for *.example.com needs:

_acme-challenge.example.com.  CNAME  <expected_cname>

The challenge’s cname_record_name already accounts for this; publish what it says and the wildcard case takes care of itself.

A wildcard order can only be signed by a wildcard-capable authority. If none is available the certificate fails rather than falling back to one that cannot issue it.

Key algorithms

key_algorithm defaults to ecdsa-p256 and cannot be changed after creation — issue a new certificate to move to a different algorithm.

ECDSA

ecdsa-p256 (default), ecdsa-p384. Smaller keys, faster handshakes. Prefer these unless a client requires RSA.

RSA

rsa-2048, rsa-4096. For older clients and appliances that will not negotiate an ECDSA chain.

Get started

Products

Platform

Help

Issuing a certificate