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.
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.
/api/v2/certsList certificates
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | 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 |
name | string | Name contains. |
domain | string | SAN contains (part of a domain or IP). |
scope | string | site = site certificate; ip = platform IP certificate; panel = panel certificate (used by the controller's HTTPS listener). |
enabled | boolean | Whether enabled |
expire_days | integer | Only list certificates expiring within N days (including expired ones). |
id | integer | Exact certificate ID match. |
ids | string | Comma-separated certificate IDs (at most 200); matches any of them. Combined with id as an intersection. |
des | string | Remark contains. |
type | string | Certificate type. |
dns_api_id | integer | Certificates using this DNS API credential. |
dns_api_ids | string | 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 |
q | string | 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). |
domains | string | Comma-separated domains or IPs; matches certificates whose SAN contains any of them (exact match). |
issue_state | string | ACME issuance state (uploaded certificates have none). |
kind | string | domain = SAN contains a domain; ip = SAN is all IPs. |
/api/v2/certsCreate certificate
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | 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
| Field | Type | Description |
|---|---|---|
acme | CertAcmeSummary | 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.). |
cert | string | Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key). |
des | string | Description |
enabled | boolean | Whether enabled |
key | string | Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key. |
nameRequired | string | Name |
scope | string | Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate. |
type | string | custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API. |
/api/v2/certs/acme-statesGet ACME issuance states in batch
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
idsRequired | string | Certificate IDs, comma-separated, at most 200. |
/api/v2/certs/batchBatch-create ACME certificates
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | 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
| Field | Type | Description |
|---|---|---|
acme_account_id | integer | 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_renew | boolean | Defaults to true if omitted. |
des | string | Description |
dns_api_id | integer | DNS API credential used for DNS-01 validation (for ACME certificates). |
itemsRequired | CertAcme[] | Issuance states. |
type | string | custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API. |
/api/v2/certs/batch-issueBatch reissue or renew ACME certificates
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
idsRequired | integer[] | Certificate IDs. |
/api/v2/certs/zerossl-ipsList IPs eligible for ZeroSSL certificates
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
/api/v2/certs/{id}Get certificate
Authentication: User (some parameters admin only)
/api/v2/certs/{id}Update certificate
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
acme | CertAcmeSummary | 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.). |
cert | string | Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key). |
des | string | Description |
enabled | boolean | Whether enabled |
key | string | Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key. |
nameRequired | string | Name |
scope | string | Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate. |
type | string | custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API. |
/api/v2/certs/{id}Delete certificate
Authentication: User (some parameters admin only)
/api/v2/certs/{id}/acmeGet certificate ACME issuance status
Authentication: User (some parameters admin only)
/api/v2/certs/{id}/acmeUpdate certificate auto-renewal switch
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
auto_renewRequired | boolean | Defaults to true if omitted. |
/api/v2/certs/{id}/bindBind certificate to sites
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
site_idsRequired | integer[] | Sites using this certificate. |
/api/v2/certs/{id}/issueReissue ACME certificate
Authentication: User (some parameters admin only)
/api/v2/certs/{id}/private-keyExport certificate private key
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
password | string | Current login password. |
totp_code | string | Current 6-digit TOTP code; the account must have TOTP enabled. |
Certificates object
| Field | Type | Description |
|---|---|---|
acme | CertAcmeSummary | 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.). |
acme_account_id | integer | 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_end | string | End of the renewal window suggested by the CA via ARI. |
ari_start | string | Renewal window suggested by the CA via ARI; null = none given by the CA, renew cert.acme.renew_before_days days before expiry. |
auto_renew | boolean | Defaults to true if omitted. |
cert | string | Certificate chain PEM (leaf first, intermediates completed, root excluded); no private key (export it only via POST /certs/{id}/private-key). |
cert_id | integer | Certificate ID. |
challenge | string | Validation method: http-01, dns-01, or http-file (ZeroSSL file validation for zerossl_api). |
created_at | string | Created at |
des | string | Description |
dns_api_id | integer | DNS API credential used for DNS-01 validation (for ACME certificates). |
enabled | boolean | Whether enabled |
err_times | integer | Number of failures in the current round. |
failed | integer | Number of failed items. |
fingerprint | string | SHA-256 fingerprint of the leaf certificate (lowercase hex). |
id | integer | Record ID |
idsRequired | integer[] | Certificate IDs. |
issued_at | string | Time of the last successful issuance. |
issuer | string | Certificate issuer. |
items | CertAcme[] | Issuance states. |
key | string | Private key PEM (PKCS#1/PKCS#8/SEC1, must not be encrypted); omit when replacing the certificate to verify against the existing key. |
last_error | string | Last error |
name | string | Name |
names | string[] | SANs (domains, wildcard domains or IPs); falls back to CN when there is no SAN. |
next_retry_at | string | 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_at | string | After a renewal ends in failure, the earliest time the renewal scan will retry. |
not_after | string | Certificate expiry time. |
not_before | string | Time the certificate becomes valid. |
ocsp | boolean | The leaf certificate carries an OCSP URL (nodes can staple). |
ok | integer | Number of items queued for issuance. |
password | string | Current login password. |
renewing | boolean | The current round is a renewal (the old certificate stays in use on failure). |
scope | string | Certificate scope: site = site certificate; ip = platform IP certificate; panel = panel certificate. |
site_ids | integer[] | Sites using this certificate. |
state | string | pending = queued or waiting to retry; running = issuing; issued = issued; failed = retries exhausted (alert sent). |
tenant_id | integer | Owning tenant; null = platform IP certificate. |
totp_code | string | Current 6-digit TOTP code; the account must have TOTP enabled. |
type | string | custom = uploaded; lets/zerossl = issued via ACME; zerossl_api = issued via the paid ZeroSSL REST API. |
updated_at | string | Updated at |
version | integer | Certificate content version; incremented on each replacement. |
zerossl_order_id | string | Current ZeroSSL order ID of a zerossl_api certificate; empty = no order yet. |
zerossl_order_state | string | 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.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"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"
}