Skip to main content

CA connectors

Issue from a commercial CA through its own REST API instead of ACME. A CA connection holds the vendor, the API address, the credential and the products your account may order; CertAutoPilot proves control of the domain the way the vendor asks, places the order, polls the vendor until the certificate is issued, stores it and removes any DNS record it wrote. The shipped vendor is GlobalSign Atlas.

CertAutoPilot is not an intermediary. You obtain the credential from the vendor, the contract and the certificate quota (or credits) are yours, and every order is placed on your own account. CertAutoPilot does not track quota — a refused order is reported and you add quota at the vendor.

Vendors not offered for new connections

A vendor can stay in a release only for the connections made before: those keep working (issue, renew, test, edit), but a new connection for it is refused with CA_VENDOR_NOT_OFFERED and the form does not list it. The vendor catalogue marks such a vendor "listed": false.

Where it lives​

Settings → Certificate Authorities → CA Connectors (/settings/certificate-authorities?tab=ca-connectors). The page has one tab per issuer family: ACME Accounts, Custom ACME CAs, Microsoft AD CS and CA Connectors. The edit forms keep their own pages.

Connections are project-scoped, like AD CS connections. Any project member can read them; creating, editing, deleting, testing and generating a client CSR need the project admin role.

The connection object​

FieldNotes
NameUnique per project.
VendorOne of the shipped vendors offered for new connections (globalsign). Fixed after creation.
Base URLThe vendor's API endpoint. May be left empty when the vendor has one well-known address (GlobalSign Atlas: https://emea.api.hvca.globalsign.com:8443/v2) — the catalogue names it as default_base_url. https is required; plain http is accepted only for a loopback address on a connection that allows private networks. No embedded credentials, no fragment.
Auth scheme + fieldsThe vendor declares the schemes it accepts and the fields each one needs (GlobalSign Atlas: atlas_mtls — API key, API secret, and an mTLS client certificate with its key). The fields are write-only: the API never echoes them, a credential_hint shows a masked hint, and has_credentials says whether any are stored.
Client certificateFor a vendor that authenticates with mutual TLS: the connection shows the certificate's subject, issuer and expiry (client_cert), and Generate CSR makes the key for it inside CertAutoPilot. See mTLS client certificate.
ProductsThe catalogue your account may order — code, display name, whether it is a wildcard product, and exactly one default. An empty list on create is filled from the vendor's defaults (GlobalSign Atlas: one product, account — the account's validation policy decides what is issued). Up to 50 products, codes unique, code ≤ 64 and name ≤ 128 characters; when no product is marked default the first one becomes it.
Allow private networkOff by default. When on, the base URL may point at a private or loopback address (an on-prem gateway in front of the vendor, or a test server). Link-local, cloud-metadata and DNS-rebinding destinations stay refused. Turning it on is logged at creation and update time.
NotesFree text.
Statusactive, inactive or error. A vendor authentication failure during an order sets error and records the vendor code in Last error; a successful test clears it.

Editing credentials. A PATCH with an auth object is merged over the stored fields: a field you leave out keeps its value, a field sent as an empty string is cleared, and the whole set is validated again under the (possibly new) scheme. Sending no auth at all leaves the credential untouched, so renaming a connection never requires re-entering the key. A base-URL change needs every stored secret entered again in the same request (CA_CONNECTION_CREDENTIAL_REQUIRED; for GlobalSign Atlas the API secret — naming only the API key is refused) — a stored secret never follows a connection to a new address. The mTLS private key is not asked for: it signs the TLS handshake and is never sent to the server.

Test calls the cheapest vendor request that proves the credential without placing an order (GlobalSign Atlas: log in and read the issuance quota). The result is one of three: credential accepted by the vendor, vendor reachable but the API offers no call that proves the credential without an order (reported as success with that note), or a failure naming the vendor code. A test never buys anything. When the connection's mTLS client certificate has expired or expires within 30 days, the success message says so.

mTLS client certificate​

Some vendors accept API requests only over a TLS connection that presents a client certificate (GlobalSign Atlas). Without it the TLS handshake itself fails, so the connection cannot be used until one is in place — but it can be saved without one, because the key is made after saving:

  1. Save the connection with the API key and secret.
  2. On the connection's page, the mTLS client certificate card offers Generate CSR. CertAutoPilot makes an RSA-2048 key, keeps it encrypted with the connection's credential (it is never shown or returned) and shows the certificate request — copy or download it.
  3. Create the certificate for that CSR in the vendor's portal (GlobalSign Atlas: see the GlobalSign page) and paste it into Certificate issued for this CSR, then Save certificate. CertAutoPilot checks that it belongs to the new key and switches to that key.
  4. Run Test.

Generating another CSR later (before the certificate expires) keeps the current key and certificate working until the certificate for the new CSR is pasted. Use my own certificate and key instead takes a certificate and private key made elsewhere. A pasted certificate that does not belong to the stored key (nor to the key of the last generated CSR) is refused.

Capabilities​

Each vendor ships a fixed capability map — what CertAutoPilot can do with the vendor, never what one account allows — visible in the vendor catalogue (GET /projects/{projectId}/ca-connector-vendors) and on the connection page. A vendor that describes its account (reads_account, GlobalSign Atlas) takes names per certificate, wildcards and key types from the account's live policy instead; the connection page then says Set by the account policy:

CapabilityMeaning
revoke / reissue / cancelWhether CertAutoPilot can perform the operation through the vendor. When revoke is false the Revoke action is hidden for the certificate and the API answers 422 ISSUER_UNSUPPORTED_OPERATION. GlobalSign Atlas revokes through its API — the current version or an earlier one.
max_sansNames per certificate the connector supports (1 = single-domain only; 0 = no connector limit — GlobalSign Atlas, whose account policy decides). Exceeding it is refused at submit with CA_CONNECTOR_SAN_LIMIT.
wildcardWhether a wildcard name may be requested (GlobalSign Atlas: yes — Atlas decides for the account and refuses before issuing anything).
supported_key_types / default_key_typeThe key types CertAutoPilot can request from the vendor and the one the form pre-selects (narrowed by the account policy where it is read).
dcv_methods / dcv_record_typesFor a vendor that asks for a record per order: how it validates the domain and which record types it may ask for (CNAME and/or TXT). Empty for GlobalSign Atlas, which validates domains on the account.

The catalogue also says, per vendor, whether it is offered for new connections (listed), whether it validates domains on the account so a certificate's zone is optional (zone_optional), how it can prove a domain not validated there yet (domain_validation_methods: dns — automatic through the zone — manual_dns, http, email), whether it describes the account live (reads_account), whether it offers Rekey (rekey: a copy of an active certificate with a new key — GlobalSign Atlas), and its default_base_url.

Renew and Re-issue. Unless the vendor can reissue an existing order for free (reissue: true and an order subscription that still runs), every renewal and every re-issue requests a new certificate from the vendor — one unit of your quota or credit. The confirm dialogs say which. An active connector certificate can be re-issued only when the reissue is free; otherwise the API answers 422 ISSUER_UNSUPPORTED_OPERATION and Renew is the way to a new certificate. Re-issue of a pending, failed or expired certificate requests a new certificate. If such a re-issue of an expired certificate fails after the order was placed, automatic renewal of the certificate is stopped (so the renewal sweep does not buy another one) — Last error says so, and a manual Renew or Re-issue places a new order.

The ISSUER_UNSUPPORTED_OPERATION answer is structured:

{
"error": "ISSUER_UNSUPPORTED_OPERATION",
"message": "GlobalSign Atlas does not support revoke",
"issuer_type": "ca_connector",
"vendor": "globalsign",
"operation": "revoke"
}

The same answer covers Microsoft AD CS and imported certificates, which do not support revocation from CertAutoPilot.

Requesting a certificate​

In the issue wizard pick CA Connector as the source, then a connection and a product. The product defaults to the connection's default; for a vendor with wildcard products, a domain starting with *. needs a wildcard product and a plain domain needs a non-wildcard one (GlobalSign Atlas has no wildcard products: the account decides). Key types are limited to the vendor's list and default to its default type.

Zone. As for ACME certificates, the wizard matches the domain to the longest zone that covers it and shows it below the domain field; you can move it to another zone. How the domain is validated decides whether a zone is needed:

  • A vendor that asks for a validation record per order needs a zone with a DNS credential on every certificate — that is where the record is written. The submit is refused with ISSUER_REQUIRES_ZONE (no zone) or ISSUER_REQUIRES_DNS_CREDENTIAL (zone without a credential).
  • A vendor that validates domains on the account (zone_optional, GlobalSign Atlas) needs the zone only for a domain it has not validated yet. Without a zone, a domain the vendor already validated issues at once; one it has not validated fails with DOMAIN_NOT_VALIDATED before anything is ordered. A zone that is given must still have a DNS credential.

A vendor that asks for a record per order has no manual fallback: CertAutoPilot always writes that record. A vendor that validates domains on its account can also let you prove a domain yourself — a DNS record you publish, a file on the web server, or an approval e-mail (GlobalSign Atlas). Renewal mode is always the threshold (custom) — a vendor API offers no ARI — and auto-renew works normally.

Submit-time refusals (all HTTP 400, with the code at the start of error):

CodeCause
ISSUER_REQUIRES_ZONENo zone_id on the request, for a vendor that needs one.
ISSUER_REQUIRES_DNS_CREDENTIALThe zone has no DNS credential.
CA_CONNECTOR_SAN_LIMITMore names than the vendor's max_sans.
CA_PRODUCT_INVALIDThe product code is not on the connection, or the connection has no products.
CA_VENDOR_UNKNOWNThe connection names a vendor this build does not ship.
CA_CONNECTION_NOT_ACTIVEThe connection is flagged error.
CA_RENEWAL_THRESHOLD_TOO_SHORTThe renewal window is not longer than the CA Order Deadline.
CA_RENEWAL_THRESHOLD_TOO_LONGThe renewal window is not shorter than the longest validity the account's policy grants: every certificate would renew halfway through its life and twice as many would be ordered.
(message only)Wildcard/product mismatch; a wildcard on a vendor without wildcard products; key type not accepted; vendor-specific local rules.

The certificate policy applies as for any issuer: allowed_issuer_types accepts ca_connector, allowed_issuer_ids accepts connection ids.

Lifecycle​

A connector issuance is a chain of jobs. The certificate sits in issuing (or renewal_in_progress for a renewal) for the whole wait — there is no new status — and the detail page shows the vendor order (order id, validation record, how many times the vendor was asked, the last answer, the deadline).

  1. ca_place_order — loads the connection and the DNS writer for the zone before touching anything (a misconfigured certificate fails here without spending an order).
    • For a vendor that validates domains on the account it first asks the vendor which names are validated (free). If every name is, it orders at once — no record, no zone needed. Otherwise it starts (or renews) the validation for the zone's domain when the name is under it — so one validation covers every name in the zone — else for the name itself, writes the vendor's record into the zone and hands the wait to ca_poll_order without ordering anything.
    • Then it generates or reuses the key, builds the CSR, places the order, records the vendor's order id, writes the vendor's per-order validation record when the vendor asks for one (CNAME or TXT) and arms the poll. A cert.requested timeline event carries the vendor, order id and record.
  2. ca_poll_order — a self-rescheduling gate that holds no worker between ticks. It first waits until the record is visible on the configured resolvers (the same propagation settings as DNS-01: resolver list, "allow partial", "skip pre-check") and does not ask the vendor until it is. For an account-level validation it then asks the vendor to check the domain; when every name is validated it queues a new ca_place_order that orders, and removes the records. For an order it polls the vendor with growing intervals until the certificate is issued, the vendor refuses, or the order deadline passes.
  3. ca_cleanup_dcv — removes the record from the zone once it is no longer needed. If removal fails on every attempt the order is marked cleanup failed and the detail page tells you which record to delete by hand.

So with an account-level vendor nothing is bought until every domain is validated: a validation the vendor refuses (DOMAIN_VALIDATION_FAILED) or one that does not finish before the deadline costs nothing, and a renewal keeps its normal retry ladder.

Order deadline. Settings → General → CA Order Deadline (ca_order_deadline_hours, 1–168, default 72) bounds how long the domain validation and a placed order may wait together. A vendor may cap it lower. Past the deadline the order (or the validation) is closed as expired, the certificate returns to pending (first issuance) or onto the renewal ladder with CA_ORDER_DEADLINE_EXCEEDED in Last error, and Reissue starts again.

Failures after an order exists are terminal. A vendor refusal (authentication, request rejected, quota, CA-side error), a DNS write failure after the order was placed, or an unrecognised vendor answer closes the order as failed and never re-orders on its own — a retry could buy a second certificate. The certificate goes back to pending (first issuance) or onto the renewal-failure ladder (renewal; the ladder stops at once when a paid order is behind the failure), Last error reads <CODE>: <explanation>, a _FAILED audit entry is written, and a notification fires: cert.issuance_failed for a first issuance or re-issue, cert.renewal_failed for a renewal. A vendor authentication failure also sets the connection's status to error. A failure before any order exists (vendor unreachable, a refusal before ordering such as QUOTA_REACHED or POLICY_MISMATCH, a domain not validated) bought nothing.

An unanswered order request. When the order request was sent but got no usable answer (VENDOR_NO_RESPONSE), the vendor may or may not have created the certificate. A vendor that can be asked again safely is asked again with the same request — GlobalSign Atlas first looks in the account's issued certificates for one with the same public key (its list lags behind issuance by about 20 seconds, so it keeps looking for a while) — so nothing is bought twice. If the job runs out of attempts first, the certificate waits in pending with VENDOR_NO_RESPONSE, and Reissue continues the same request. A vendor that cannot be asked again closes such a request instead: check the vendor panel before re-issuing.

Renewal. The renewal sweep enqueues ca_place_order for a connector certificate when its threshold is reached; the key is rotated or reused per the certificate's key-rotation policy. It is a new certificate request unless the vendor reissues the existing order for free.

Recovery. A scheduler sweep (Stuck CA Order Recovery) re-arms the poll for an order idle for more than 90 minutes whose chain died, and closes an order whose certificate no longer waits for it (cleaning up its record). An order record is kept for 7 days past its deadline.

When an order ends in failure or expiry, the certificate, the order state and the notification are written first and the ca_poll_order job is then marked failed with the same code — so the Jobs page and the job_total{type="ca_poll_order",status="failed"} metric show connector failures. The order state records the step it reached (initialized → domain_validation → domains_validated → order_requested → order_placed → dcv_presented → dcv_propagated → storing → completed, or superseded).

DNS records written​

The record CertAutoPilot writes is exactly what the vendor returns — an owner name inside your zone, a type (CNAME or TXT) and a value. GlobalSign Atlas uses a TXT at _globalsign-domain-verification.<domain>. Every one of the 19 DNS providers can write both types; the provider-specific rules are on each DNS provider page (RFC 2136 grants must allow CNAME for a vendor that asks for one; GoDaddy and Hostinger enforce minimum TTLs; Namecheap rewrites the whole host list). The DNS credential test has an opt-in Also test CA-connector DCV writing (CNAME + TXT) leg that creates and removes a TXT and a CNAME probe at _cap-dcv-test-<timestamp>.<zone> — run it once per credential before relying on a connector.

Pick the zone that will contain the vendor's record. CertAutoPilot only ever writes into the zone the certificate selected; a vendor that validates at the registrable domain needs that zone selected, not a sub-zone — otherwise the write is refused as outside the zone and the order fails with DCV_WRITE_FAILED. The ca_cleanup_dcv job cannot be cancelled from the Jobs page — cancelling it would leave the record in your zone with nothing flagging it; a cleanup that fails all its attempts marks the order DCV cleanup failed on the certificate page so you can delete the record by hand.

Base URL rules. https:// is required; a private or loopback address (10.x, 192.168.x, 127.0.0.1, localhost, [::1]) is accepted only when Allow private network is enabled on the connection — the form says so at save time instead of the first order failing at dial time; link-local and cloud-metadata addresses are always refused; the address must answer directly (a redirect is reported as VENDOR_REDIRECT, never followed). Connect and TLS-handshake time-outs are bounded separately (15 s / 10 s), so a host that silently drops connections (a firewall on the path) is reported as VENDOR_UNREACHABLE and retried, never mistaken for an unanswered order. Internationalised domain names are stored and ordered in their punycode (A-label) form.

API​

MethodPathRole
GET/projects/{projectId}/ca-connector-vendorsany member — the vendor catalogue (auth schemes, capabilities, default products, listed, zone_optional, default_base_url, reads_account)
GET / POST/projects/{projectId}/ca-connectionsread: viewer · create: project admin
GET / PATCH / DELETE/projects/{projectId}/ca-connections/{id}read: viewer · writes: project admin
POST/projects/{projectId}/ca-connections/{id}/testproject admin — vendor probe
POST/projects/{projectId}/ca-connections/{id}/client-csrproject admin, 10 per minute per project — new mTLS client key, answers {csr, connection}
GET/projects/{projectId}/ca-connections/{id}/accountoperator, 60 per minute per project — the vendor account read live (policy, counters, validated domains) for a vendor with reads_account; cached a minute, ?refresh=true reads again
GET/projects/{projectId}/ca-connections/{id}/issued?days=operator, 60 per minute per project (shared with /account) — the certificates the vendor account issued in the last 1–365 days, held ones linked
GET/projects/{projectId}/ca-connections/{id}/account/domains/{ref}operator — one domain validation of the vendor account in detail
DELETE/projects/{projectId}/ca-connections/{id}/account/domains/{ref}project admin, 10 per minute per project — removes a domain validation from the vendor account; audited CA_ACCOUNT_DOMAIN_REMOVED
POST/projects/{projectId}/certificates/{id}/ca-validation/canceloperator — stops a domain validation that has ordered nothing; audited CERT_VALIDATION_STOPPED
GET/projects/{projectId}/certificates/{id}/ca-validation/emailsoperator, 30 per minute per project — the addresses the vendor accepts for the approval e-mail of a validation waiting for one
POST/projects/{projectId}/certificates/{id}/ca-validation/emailoperator, 5 per minute per project — {ref, email_address}: asks the vendor to send the approval e-mail; audited CERT_VALIDATION_EMAIL_SENT
GET/projects/{projectId}/ca-connections/{id}/usageviewer — certificates referencing the connection

Create body: name, vendor, base_url (optional when the vendor has a default_base_url), auth_scheme (optional when the vendor has one), auth (object of the scheme's fields), products (optional), notes, allow_private_network. Update takes the same fields as optional; vendor cannot change. A connection carries client_cert (subject, issuer, not_after, csr_pending, csr_pem) for a vendor with mutual TLS. Delete answers 409 with the blocking certificates while any certificate references the connection. Validation refusals answer 422. A certificate is created with issuer_type: "ca_connector", ca_connection_id and optionally ca_product_code; its detail carries ca_connection and the latest ca_order_state. Audit actions: CA_CONNECTION_CREATED / UPDATED / DELETED / TESTED / CSR_GENERATED (credential fields redacted).

Troubleshooting​

SymptomWhere to look
Submit refused with ISSUER_REQUIRES_DNS_CREDENTIALLink a DNS credential to the zone (Settings → Zones).
ca_place_order failed before an order id appearsThe job log names the step — connection load, DNS writer, domain validation, key, CSR or a transport error to the vendor. Nothing was ordered; fix and Reissue.
Last error DOMAIN_NOT_VALIDATED: …The vendor validates domains on its account, the domain is not validated there and the certificate has no zone. Validate it in the vendor portal and Reissue, or issue a new certificate with a zone that has a DNS credential (a certificate's zone is fixed when it is created). Nothing was ordered.
Last error DOMAIN_VALIDATION_FAILED: …The vendor did not accept the validation record. Check the record is visible in public DNS (the order card and the job log name it), then Reissue. Nothing was ordered.
Last error VENDOR_UNREACHABLE: …The vendor API could not be reached (outbound firewall, DNS or proxy on this side). Nothing was ordered. Fix access, Test connection, then Reissue. Renewals retry on their own ladder; a running poll retries until the deadline.
Last error VENDOR_NO_RESPONSE: …The order request was sent but never answered usably; a certificate may exist. See An unanswered order request.
Last error DCV_WRITE_FAILED: …The DNS provider refused the record permanently. Fix the zone's DNS credential (test with the DCV option) and Reissue.
Last error VENDOR_CERT_MISMATCH: … / VENDOR_KEY_MISMATCH: … / VENDOR_CERT_INVALID: …The vendor's certificate does not name the ordered domains, does not carry the certificate's key, or is expired / not yet valid / does not extend the current one. It was refused and never stored. Contact the vendor with the order id.
Last error CA_PRODUCT_INVALID: product "…" is no longer definedThe product the certificate was created with was removed from the connection's catalogue. CertAutoPilot never orders a substitute silently: add the code back, or re-issue the certificate with another product.
Renewal ended in renewal_failed after one attemptThe failure happened after a paid order existed (vendor refusal at check, deadline, invalid certificate). The ladder stops on purpose — an automatic retry would buy another certificate — and the daily renewal rescue skips connector certificates. Fix the cause, then Renew or Reissue by hand.
Certificate create refused with CA_RENEWAL_THRESHOLD_TOO_SHORTThe renewal window must be longer than the CA Order Deadline (default 72 h ⇒ at least 4 days), otherwise a renewal could still be waiting at the vendor when the old certificate expires. Raise renewal_threshold_days or lower the deadline.
Certificate create or renewal settings refused with CA_RENEWAL_THRESHOLD_TOO_LONGThe account issues certificates shorter than the renewal window (for example 30-day certificates with a 30-day window). Choose a window below the validity; the issue wizard suggests a third of it.
Cancelled the poll job from the Jobs pageThe vendor order (or validation) is closed as cancelled and its record removed; a later Reissue starts again.
Connection update refused with CA_CONNECTION_ORDERS_PENDINGThe base URL (or the auth scheme) cannot change while orders placed at the current address are still pending. Wait for them, or cancel their poll jobs and let the stuck-order sweep close them.
Certificate create refused with CA_CONNECTION_NOT_ACTIVEA failed Test connection or an authentication failure during an order flagged the connection error. Fix the cause, run Test connection again (or let the next successful order clear it).
Order sits at record not yet visibleThe record exists in the zone but the configured resolvers do not see it yet — the job log lists lagging authoritative servers. Adjust the resolvers or wait; the deadline bounds it.
CA_ORDER_DEADLINE_EXCEEDEDThe vendor never validated or issued within the deadline; the record was removed. Raise the deadline if the vendor is slow, then Reissue.
DCV cleanup failed on the order cardDelete the named record from the zone by hand.

Vendor-specific codes and steps: GlobalSign Atlas.

See also​