Management API

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/est

getEst

The EST server: endpoints, Issuing CA, profiles, host names, enrolled certificates, settings

Everything /admin/est draws. The six RFC 7030 operations at this realm’s base URL; the EST Issuing CA and whether the hierarchy is built; the nine profiles with what each needs, whether est.allowedProfiles allows it and its labelled URLs; the five profiles never issued over an enrollment protocol and why; the credentials EST accepts; the certificate host names registered in the realm; the certificates enrolled over EST (paged, certificatesPage), with no private key; the mode note; and the est.* settings, which are written through POST /admin-api/config/set-many.

Mirrors GET /admin/cert-issuance on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
certificatesPage query integer   Which page of enrolled certificates.
per query integer   Rows per page.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The EST server as the page draws it.

Member Type Required What it is
actions list    
actions[] string    
authentication object    
authentication.basic boolean    
authentication.certificate boolean    
authentication.credentials list    
authentication.credentials[].kind string    
authentication.credentials[].managedAt string    
authentication.credentials[].what string    
authentication.serverKeyGeneration boolean    
certificates object    
certificates.paging object    
certificates.paging.firstRow integer    
certificates.paging.lastRow integer    
certificates.paging.noun string    
certificates.paging.page integer    
certificates.paging.pages integer    
certificates.paging.param string    
certificates.paging.perPage integer    
certificates.paging.total integer    
certificates.rows list    
certificates.rows[].account string, or null    
certificates.rows[].entry object    
certificates.rows[].entry.id string    
certificates.rows[].entry.kind string    
certificates.rows[].entryUri string    
certificates.rows[].issuedAt string, or number, or null    
certificates.rows[].keyAlg string    
certificates.rows[].keySource string, or null    
certificates.rows[].names list    
certificates.rows[].names[] string    
certificates.rows[].notAfter string    
certificates.rows[].notBefore string    
certificates.rows[].profile string, or null    
certificates.rows[].replaces string, or null    
certificates.rows[].requestedBy object    
certificates.rows[].requestedBy.admin boolean    
certificates.rows[].requestedBy.id string    
certificates.rows[].requestedBy.kind string    
certificates.rows[].revoked object    
certificates.rows[].revoked.at string, or number, or null    
certificates.rows[].revoked.by string    
certificates.rows[].revoked.reason string    
certificates.rows[].serialHex string    
certificates.rows[].status string    
certificates.rows[].subject string, or null    
certificates.rows[].thumbprint string, or null    
certificates.rows[].via string, or null    
csrAttributes object    
csrAttributes.signatureAlgorithms list    
csrAttributes.signatureAlgorithms[].name string    
csrAttributes.signatureAlgorithms[].oid string    
defaultProfile string, or null    
enabled boolean    
endpoints list    
endpoints[].labelFormUrl string, or null    
endpoints[].method string    
endpoints[].operation string    
endpoints[].section string    
endpoints[].url string    
endpoints[].what string    
hierarchy object    
hierarchy.authority object    
hierarchy.authority.certificatePem string    
hierarchy.authority.keyAlg string    
hierarchy.authority.notAfter string    
hierarchy.authority.notBefore string    
hierarchy.authority.serialHex string    
hierarchy.authority.subject string    
hierarchy.authority.thumbprint string    
hierarchy.built boolean    
hierarchy.chainPem list    
hierarchy.chainPem[] string    
hierarchy.note string    
hostNames list    
hostNames[].entry object    
hostNames[].entry.id string    
hostNames[].entry.kind string    
hostNames[].entryUri string    
hostNames[].hostNames list    
hostNames[].hostNames[] string    
keyAlgorithms list    
keyAlgorithms[] string    
labelForm object    
labelForm.base string    
labelForm.note string    
mode object    
mode.current string    
mode.development string    
mode.product string    
mode.where string    
monitor string    
page string    
profiles list    
profiles[].allowed boolean    
profiles[].id string    
profiles[].isDefault boolean    
profiles[].needs string, or null    
profiles[].urls map    
profiles[].urls.{key} string    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
refusedProfiles list    
refusedProfiles[].id string    
refusedProfiles[].why string    
revocationReasons list    
revocationReasons[] string    
settings object    
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string, or null    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer    
settings.groups list    
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map    
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list    
settings.groups[].settings[].csvValues[] string, or number, or boolean, or null    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] object   Nested deeper than this page draws.
settings.groups[].settings[].description string    
settings.groups[].settings[].editRefusal string    
settings.groups[].settings[].editable boolean    
settings.groups[].settings[].enumValues list    
settings.groups[].settings[].enumValues[] string, or number, or boolean, or null    
settings.groups[].settings[].env list, or string    
settings.groups[].settings[].env[] object   Nested deeper than this page draws.
settings.groups[].settings[].group string    
settings.groups[].settings[].key string    
settings.groups[].settings[].label string    
settings.groups[].settings[].legacyEnv list, or string    
settings.groups[].settings[].legacyEnv[] object   Nested deeper than this page draws.
settings.groups[].settings[].masked boolean    
settings.groups[].settings[].max number    
settings.groups[].settings[].min number    
settings.groups[].settings[].ordered boolean    
settings.groups[].settings[].overridden boolean    
settings.groups[].settings[].realmSettable boolean    
settings.groups[].settings[].restartReason string    
settings.groups[].settings[].selectAll object    
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[] object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[] object   Nested deeper than this page draws.
settings.groups[].settings[].source string    
settings.groups[].settings[].step number    
settings.groups[].settings[].text string, or null    
settings.groups[].settings[].type string    
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] object   Nested deeper than this page draws.
settings.overridden list    
settings.overridden[] string    
settings.page string    
settings.setWith string    
settings.settingCount integer    
settings.sharedWith map    
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string    
settings.sharedWith.{key}[].path string    
specifications list    
specifications[] string    
title string    

POST /admin-api/est/add-host-name

addEstHostName

Register a certificate host name on an entry

A dNSName or iPAddress is issued in a certificate — over ACME, EST or SCEP — only when it is registered on the entry the certificate names. Adding one already there changes nothing.

Mirrors POST /admin/est on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
hostName string yes A DNS name or an IP address.
identifier string yes The username or application identifier.
kind one of person, application yes Whether identifier names a person (a username) or an application (its identifier).

200: The entry’s host names afterwards.

Member Type Required What it is
entry object    
entry.id string    
entry.kind string    
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  
status integer    
unchanged boolean    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
entry object    
entry.id string    
entry.kind string    
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  
status integer    
unchanged boolean    
why string    

POST /admin-api/est/issue-server-key

issueEstServerKey

Issue a certificate with a key pair this service generates

The console’s /serverkeygen (RFC 7030 section 4.4): a key pair of keyAlg is generated, certified for profile by this realm’s EST Issuing CA for the person or application named, written onto that entry with a sealed copy of the private key, and returned ONCE as privateKeyPem. A KEM key (ML-KEM) is certified only for key-encipherment.

Mirrors POST /admin/est on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
identifier string yes The username or application identifier.
keyAlg one of rsa-2048, rsa-3072, rsa-4096, ec-p256, ec-p384, ec-p521, ed25519, ml-dsa-44, ml-dsa-65, ml-dsa-87, slh-dsa-sha2-128s, slh-dsa-sha2-128f, slh-dsa-sha2-192s, slh-dsa-sha2-192f, slh-dsa-sha2-256s, slh-dsa-sha2-256f, slh-dsa-shake-128s, slh-dsa-shake-128f, slh-dsa-shake-192s, slh-dsa-shake-192f, slh-dsa-shake-256s, slh-dsa-shake-256f, mldsa44-rsa2048-pss-sha256, mldsa44-rsa2048-pkcs15-sha256, mldsa44-ed25519-sha512, mldsa44-ecdsa-p256-sha256, mldsa65-rsa3072-pss-sha512, mldsa65-rsa3072-pkcs15-sha512, mldsa65-rsa4096-pss-sha512, mldsa65-rsa4096-pkcs15-sha512, mldsa65-ecdsa-p256-sha512, mldsa65-ecdsa-p384-sha512, mldsa65-ed25519-sha512, mldsa87-ecdsa-p384-sha512, mldsa87-ed448-shake256, mldsa87-rsa3072-pss-sha512, mldsa87-rsa4096-pss-sha512, mldsa87-ecdsa-p521-sha512, ml-kem-512, ml-kem-768, ml-kem-1024   A key algorithm id from GET /admin-api/est keyAlgorithms; ec-p256 when omitted.
kind one of person, application yes Whether identifier names a person (a username) or an application (its identifier).
profile one of tls-server, tls-client, tls-server-client, digital-signature, key-encipherment, code-signing, email, timestamping, smartcard-logon   One of the nine profiles; est.defaultProfile when omitted.

200: The certificate, its chain and the private key, once.

Member Type Required What it is
certificatePem string    
chainPem list    
chainPem[] string    
errors list    
errors[] string    
keyAlg string    
message string    
ok boolean yes  
privateKeyPem string    
record object    
record.account string, or null    
record.entry object    
record.entry.id string    
record.entry.kind string    
record.entryUri string    
record.issuedAt string, or number, or null    
record.keyAlg string    
record.keySource string, or null    
record.names list    
record.names[] string    
record.notAfter string    
record.notBefore string    
record.profile string, or null    
record.replaces string, or null    
record.requestedBy object    
record.requestedBy.admin boolean    
record.requestedBy.id string    
record.requestedBy.kind string    
record.revoked object    
record.revoked.at string, or number, or null    
record.revoked.by string    
record.revoked.reason string    
record.serialHex string    
record.status string    
record.subject string, or null    
record.thumbprint string, or null    
record.via string, or null    
status integer    
target object    
target.id string    
target.kind string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
certificatePem string    
chainPem list    
chainPem[] string    
errors list    
errors[] string    
keyAlg string    
message string    
ok boolean yes  
privateKeyPem string    
record object    
record.account string, or null    
record.entry object    
record.entry.id string    
record.entry.kind string    
record.entryUri string    
record.issuedAt string, or number, or null    
record.keyAlg string    
record.keySource string, or null    
record.names list    
record.names[] string    
record.notAfter string    
record.notBefore string    
record.profile string, or null    
record.replaces string, or null    
record.requestedBy object    
record.requestedBy.admin boolean    
record.requestedBy.id string    
record.requestedBy.kind string    
record.revoked object    
record.revoked.at string, or number, or null    
record.revoked.by string    
record.revoked.reason string    
record.serialHex string    
record.status string    
record.subject string, or null    
record.thumbprint string, or null    
record.via string, or null    
status integer    
target object    
target.id string    
target.kind string    
why string    

GET /admin-api/est/monitor

getEstMonitor

What the EST server has done: requests, issuances, refusals

Everything /admin/est/monitor draws: totals of requests, issued, refused and revoked; the certificates held by status; counts by operation, profile, principal, error code and HTTP status; and the most recent requests (paged, page). Per trust realm, across every process, with no reset: the durable record is GET /admin-api/audit.

Mirrors GET /admin/est/monitor on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
page query integer   Which page of recent requests.
per query integer   Rows per page.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The counters and recent requests.

Member Type Required What it is
certificates object    
certificates.expired integer    
certificates.held integer    
certificates.revoked integer    
certificates.valid integer    
errorCodes list    
errorCodes[].count number    
errorCodes[].name string    
lastAt string, or number, or null    
operations list    
operations[].count number    
operations[].name string    
page string    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string    
paging.page integer    
paging.pages integer    
paging.param string    
paging.perPage integer    
paging.total integer    
principals list    
principals[].count number    
principals[].name string    
processes integer    
profiles list    
profiles[].count number    
profiles[].name string    
recent list    
recent[].at string    
recent[].errorCode string, or null    
recent[].failInfo string, or null    
recent[].operation string    
recent[].outcome string, or null    
recent[].principal string, or null    
recent[].profile string, or null    
recent[].serialHex string, or null    
recent[].status integer, or null    
recent[].target string, or null    
since string, or number, or null    
statuses list    
statuses[].count number    
statuses[].name string    
title string    
totals object    
totals.issued integer    
totals.refused integer    
totals.requests integer    
totals.revoked integer    

POST /admin-api/est/remove-host-name

removeEstHostName

Remove a certificate host name from an entry

Certificates already issued for the name keep it; the next request naming it is refused.

Mirrors POST /admin/est on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
hostName string yes The name to remove.
identifier string yes The username or application identifier.
kind one of person, application yes Whether identifier names a person (a username) or an application (its identifier).

200: The entry’s host names afterwards.

Member Type Required What it is
entry object    
entry.id string    
entry.kind string    
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  
status integer    
unchanged boolean    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
entry object    
entry.id string    
entry.kind string    
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  
status integer    
unchanged boolean    
why string    

POST /admin-api/est/revoke-certificate

revokeEstCertificate

Revoke a certificate enrolled over EST

Puts the serial on the EST Issuing CA’s CRL with the RFC 5280 reason given (OCSP answers revoked from then on) and marks the record on the entry.

Mirrors POST /admin/est on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
reason one of unspecified, keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, privilegeWithdrawn, aACompromise   The RFC 5280 section 5.3.1 reason; unspecified when omitted.
serial string yes The serial, from GET /admin-api/est.

200: The serial, the entry and the reason.

Member Type Required What it is
entry object    
entry.id string    
entry.kind string    
entryUri string    
errors list    
errors[] string    
family string    
message string    
ok boolean yes  
reason string    
serialHex string    
status integer    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
entry object    
entry.id string    
entry.kind string    
entryUri string    
errors list    
errors[] string    
family string    
message string    
ok boolean yes  
reason string    
serialHex string    
status integer    
why string