Version 2.4.7.20261116085428 · latest

Certificates certs

Uploaded or automatically issued HTTPS certificates. They can be bound to sites; a certificate in use by a site cannot be deleted or disabled.

Pick an endpoint to see its example call on the right.

CertificatesAuthentication: User (some parameters admin only)14 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/certsList certificates

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403
namestring Name contains.
domainstring SAN contains (part of a domain or IP).
scopestring site = site certificate; ip = platform IP certificate; panel = panel certificate (used by the controller's HTTPS listener).
Values ["site","ip","panel"]
enabledboolean Whether enabled
expire_daysinteger Only list certificates expiring within N days (including expired ones).
idinteger Exact certificate ID match.
idsstring Comma-separated certificate IDs (at most 200); matches any of them. Combined with id as an intersection.
desstring Remark contains.
typestring Certificate type.
Values ["custom","lets","zerossl","zerossl_api"]
dns_api_idinteger Certificates using this DNS API credential.
dns_api_idsstring Filter by DNS APIs: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
qstring Candidate search: matches when the name or a SAN contains the term (case-insensitive; name and SAN are ORed). May be combined with name and domain (all must hold).
domainsstring Comma-separated domains or IPs; matches certificates whose SAN contains any of them (exact match).
issue_statestring ACME issuance state (uploaded certificates have none).
Values ["pending","running","issued","failed"]
kindstring domain = SAN contains a domain; ip = SAN is all IPs.
Values ["domain","ip"]
POST/api/v2/certsCreate certificate

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data

Request body application/json

FieldTypeDescription
acmeCertAcmeSummary Issuance state summary (carried by certificate GET and list). Present only for issued certificates (type=lets/zerossl/zerossl_api); uploaded certificates (custom) do not have this field. See GET /certs/{id}/acme for the full state (challenge type, ARI window, etc.).
certstring Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key).
desstring Description
enabledboolean Whether enabled
keystring Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key.
nameRequiredstring Name
scopestring Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate.
Values ["site","ip","panel"]
typestring custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.
GET/api/v2/certs/acme-statesGet ACME issuance states in batch

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
idsRequiredstring Certificate IDs, comma-separated, at most 200.
POST/api/v2/certs/batchBatch-create ACME certificates

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data

Request body application/json

FieldTypeDescription
acme_account_idinteger Account to issue with (same as acme.acme_account_id in POST /certs); if omitted, the tenant's enabled account for the type is used first, then the platform's.
auto_renewboolean Defaults to true if omitted.
desstring Description
dns_api_idinteger DNS API credential used for DNS-01 validation (for ACME certificates).
itemsRequiredCertAcme[] Issuance states.
typestring custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.
POST/api/v2/certs/batch-issueBatch reissue or renew ACME certificates

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
idsRequiredinteger[] Certificate IDs.
GET/api/v2/certs/zerossl-ipsList IPs eligible for ZeroSSL certificates

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
GET/api/v2/certs/{id}Get certificate

Authentication: User (some parameters admin only)

PUT/api/v2/certs/{id}Update certificate

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
acmeCertAcmeSummary Issuance state summary (carried by certificate GET and list). Present only for issued certificates (type=lets/zerossl/zerossl_api); uploaded certificates (custom) do not have this field. See GET /certs/{id}/acme for the full state (challenge type, ARI window, etc.).
certstring Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key).
desstring Description
enabledboolean Whether enabled
keystring Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key.
nameRequiredstring Name
scopestring Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate.
Values ["site","ip","panel"]
typestring custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.
DELETE/api/v2/certs/{id}Delete certificate

Authentication: User (some parameters admin only)

GET/api/v2/certs/{id}/acmeGet certificate ACME issuance status

Authentication: User (some parameters admin only)

PUT/api/v2/certs/{id}/acmeUpdate certificate auto-renewal switch

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
auto_renewRequiredboolean Defaults to true if omitted.
POST/api/v2/certs/{id}/bindBind certificate to sites

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
site_idsRequiredinteger[] Sites using this certificate.
POST/api/v2/certs/{id}/issueReissue ACME certificate

Authentication: User (some parameters admin only)

POST/api/v2/certs/{id}/private-keyExport certificate private key

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
passwordstring Current login password.
totp_codestring Current 6-digit TOTP code; the account must have TOTP enabled.

Certificates object

FieldTypeDescription
acmeCertAcmeSummary Issuance state summary (carried by certificate GET and list). Present only for issued certificates (type=lets/zerossl/zerossl_api); uploaded certificates (custom) do not have this field. See GET /certs/{id}/acme for the full state (challenge type, ARI window, etc.).
read-only
acme_account_idinteger Account to issue with (same as acme.acme_account_id in POST /certs); if omitted, the tenant's enabled account for the type is used first, then the platform's.
ari_endstring End of the renewal window suggested by the CA via ARI.
ari_startstring Renewal window suggested by the CA via ARI; null = none given by the CA, renew cert.acme.renew_before_days days before expiry.
auto_renewboolean Defaults to true if omitted.
certstring Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key).
read-only
cert_idinteger Certificate ID.
challengestring Validation method: http-01, dns-01, or http-file (ZeroSSL file validation for zerossl_api).
Values ["http-01","dns-01","http-file"]
created_atstring Created at
read-only
desstring Description
dns_api_idinteger DNS API credential used for DNS-01 validation (for ACME certificates).
enabledboolean Whether enabled
err_timesinteger Number of failures in the current round.
failedinteger Number of failed items.
fingerprintstring SHA-256 fingerprint of the leaf certificate (lowercase hex).
read-only
idinteger Record ID
read-only
idsRequiredinteger[] Certificate IDs.
issued_atstring Time of the last successful issuance.
issuerstring Certificate issuer.
read-only
itemsCertAcme[] Issuance states.
keystring Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key.
last_errorstring Last error
namestring Name
namesstring[] SANs (domains, wildcard domains or IPs); falls back to CN when there is no SAN.
read-only
next_retry_atstring For a failed issuance waiting to retry (state=pending and err_times>0), the next retry time from the delayed-job queue; null otherwise.
next_try_atstring After a renewal ends in failure, the earliest time the renewal scan will retry.
not_afterstring Certificate expiry time.
read-only
not_beforestring Time the certificate becomes valid.
read-only
ocspboolean The leaf certificate carries an OCSP URL (nodes can staple).
read-only
okinteger Number of items queued for issuance.
passwordstring Current login password.
renewingboolean The current round is a renewal (the old certificate stays in use on failure).
scopestring Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate.
Values ["site","ip","panel"]
site_idsinteger[] Sites using this certificate.
read-only
statestring pending = queued or waiting to retry; running = issuing; issued = issued; failed = retries exhausted (alert sent).
Values ["pending","running","issued","failed"]
tenant_idinteger Owning tenant; null = platform IP certificate.
read-only
totp_codestring Current 6-digit TOTP code; the account must have TOTP enabled.
typestring custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API.
updated_atstring Updated at
read-only
versioninteger Certificate content version; incremented on each replacement.
read-only
zerossl_order_idstring Current ZeroSSL order ID of a zerossl_api certificate; empty = no order yet.
zerossl_order_statestring ZeroSSL order status (draft, pending_validation, issued, cancelled, etc.); empty = no order yet.

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command