Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Certificates API

3 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

DELETE/certificates/{certificateId}

Delete a certificate (staged removal when it is installed)

Refused with 409 certificate_in_use while a domain pins it.

ParameterInTypeDescription
certificateIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictcertificate_in_use
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/servers/{serverId}/certificates

List a server's custom certificates

ParameterInTypeDescription
serverIdrequiredpathstring
Response 200 · OK · application/json
CertificatesOutputBody
  • ServerCertificate[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/servers/{serverId}/certificates

Upload a custom TLS certificate (staged until the proxy is deployed)

Needs proxy:write. The leaf is the first certificate of the chain; encrypted keys, mismatching keys, expired and not-yet-valid certificates and certificates without a SAN are rejected. The key is sealed at rest and never returned.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
serverIdrequiredpathstring
Request body · application/json · required
UploadCertificateInputBody
  • certPemstringrequired
    ServerCertificate chain in PEM, leaf first
  • keyPemstringrequired
    Unencrypted private key in PEM. Write-only: sealed at rest, never returned.
  • namestringrequired
    Unique per server
Response 201 · Created · application/json
ServerCertificate
  • appliedAtstring (date-time) | nullrequired
  • changeenum: none | add | removerequired
    Staged change awaiting Deploy proxy
  • createdAtstring (date-time)required
  • daysToExpiryinteger (int64)required
    Whole days until NotAfter (negative when expired)
  • domainsstring[] | nullrequired
    Subject Alternative Names (DNS and IP)
  • fingerprintstringrequired
    SHA-256 of the leaf certificate, hex
  • idstringrequired
  • issuerstringrequired
  • namestringrequired
  • notAfterstring (date-time)required
  • notBeforestring (date-time)required
  • serverIdstringrequired
  • statusenum: pending | active | errorrequired
    pending: never applied; active: loaded by the proxy; error: expired or the proxy could not load it
  • statusMessagestringrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.