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 |