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/acme

getAcme

The ACME server: directory, Issuing CA, profiles, EAB keys, accounts, certificates, host names, settings

Everything /admin/acme draws. The absolute endpoints of this realm’s ACME server (RFC 8555) with its directory; the ACME Issuing CA; the nine certificate profiles with what each needs and whether acme.allowedProfiles allows it, and the five never issued over ACME with the reason; the External Account Binding keys (no key material, paged by credentialsPage); the accounts (paged by accountsPage); the certificates issued over ACME (paged by certificatesPage); the host names registered on entries (paged by hostNamesPage); what development and product mode change; and the acme.* 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
per query integer   Rows per page, shared by every list in the reply.
credentialsPage query integer   Which page of the EAB keys.
accountsPage query integer   Which page of the accounts.
certificatesPage query integer   Which page of the certificates.
hostNamesPage query integer   Which page of the entries with host names.
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 ACME server as the page draws it.

Member Type Required What it is
accounts object    
accounts.paging object    
accounts.paging.firstRow integer    
accounts.paging.lastRow integer    
accounts.paging.noun string    
accounts.paging.page integer    
accounts.paging.pages integer    
accounts.paging.param string    
accounts.paging.perPage integer    
accounts.paging.total integer    
accounts.rows list    
accounts.rows[].contact list    
accounts.rows[].contact[] string    
accounts.rows[].createdAt string, or number, or null    
accounts.rows[].deactivatedAt string, or number, or null    
accounts.rows[].eabKid string, or null    
accounts.rows[].entry object    
accounts.rows[].entry.id string    
accounts.rows[].entry.kind string    
accounts.rows[].entryUri string, or null    
accounts.rows[].id string    
accounts.rows[].orders integer    
accounts.rows[].status string    
accounts.rows[].thumbprint string    
actions list    
actions[] string    
authority object    
authority.intermediate string, or null    
authority.keyAlg string    
authority.notAfter string    
authority.notBefore string    
authority.note string    
authority.present boolean    
authority.root string, or null    
authority.serialHex string    
authority.signatureAlg string    
authority.subject string    
authority.thumbprint string    
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    
challengeType string    
directory string    
eabKeys object    
eabKeys.paging object    
eabKeys.paging.firstRow integer    
eabKeys.paging.lastRow integer    
eabKeys.paging.noun string    
eabKeys.paging.page integer    
eabKeys.paging.pages integer    
eabKeys.paging.param string    
eabKeys.paging.perPage integer    
eabKeys.paging.total integer    
eabKeys.rows list    
eabKeys.rows[].boundAccount string, or null    
eabKeys.rows[].boundAt string, or number, or null    
eabKeys.rows[].createdAt string, or number, or null    
eabKeys.rows[].createdBy string    
eabKeys.rows[].entry object    
eabKeys.rows[].entry.id string    
eabKeys.rows[].entry.kind string    
eabKeys.rows[].entryUri string    
eabKeys.rows[].expiresAt string, or number, or null    
eabKeys.rows[].kid string    
eabKeys.rows[].status string    
eabLifetimeS number    
enabled boolean    
endpoints object    
endpoints.account string    
endpoints.authorization string    
endpoints.certificate string    
endpoints.challenge string    
endpoints.directory string    
endpoints.finalize string    
endpoints.keyChange string    
endpoints.newAccount string    
endpoints.newNonce string    
endpoints.newOrder string    
endpoints.order string    
endpoints.orders string    
endpoints.renewalInfo string    
endpoints.revokeCert string    
hostNames object    
hostNames.paging object    
hostNames.paging.firstRow integer    
hostNames.paging.lastRow integer    
hostNames.paging.noun string    
hostNames.paging.page integer    
hostNames.paging.pages integer    
hostNames.paging.param string    
hostNames.paging.perPage integer    
hostNames.paging.total integer    
hostNames.rows list    
hostNames.rows[].entry object    
hostNames.rows[].entry.id string    
hostNames.rows[].entry.kind string    
hostNames.rows[].entryUri string    
hostNames.rows[].hostNames list    
hostNames.rows[].hostNames[] string    
identifierTypes list    
identifierTypes[] string    
mode object    
mode.current string    
mode.development string    
mode.inForce string    
mode.product string    
mode.what string    
page string    
profiles list    
profiles[].allowed boolean    
profiles[].description string    
profiles[].id string    
profiles[].isDefault boolean    
profiles[].needs string, or null    
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/acme/add-host-name

addAcmeHostName

Register a host name or address on an entry

A dns or ip identifier is authorized for an ACME account only when it is registered on the entry the account is bound to; nothing is fetched to prove control of a name. The same registration serves EST and SCEP.

Mirrors POST /admin/acme 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 (a leading *. is a wildcard registered exactly so) or an IP address.
identifier string yes The username of a person, or the identifier of an application, in this realm.
kind one of person, application yes Whether the entry is a person (ou=users) or an application (ou=applications).

200: The entry’s host names as they now stand.

Member Type Required What it is
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  

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

Member Type Required What it is
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  

POST /admin-api/acme/create-eab

createAcmeEab

Issue an External Account Binding key for a person or application (RFC 8555 section 7.3.4)

Creates an EAB key for ONE entry in this realm and answers the key id and the HMAC key IN THE CLEAR, ONCE — the key is stored sealed on the entry and no operation reads it back. The ACME account a client registers with it is bound to that entry for life, which is the administrator’s path in ACME: a key created here for somebody else’s entry. The reply carries a ready-to-paste certbot line.

Mirrors POST /admin/acme 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 of a person, or the identifier of an application, in this realm.
kind one of person, application yes Whether the entry is a person (ou=users) or an application (ou=applications).
lifetimeS integer   How long it may wait before binding an account; at most acme.eabLifetimeS, which is also the default.

200: The key id, the HMAC key (once), when it expires, the directory and a certbot line.

Member Type Required What it is
alg string    
certbot string    
directory string    
errors list    
errors[] string    
expiresAt string, or number, or null    
hmacKey string    
kid string    
message string    
ok boolean yes  
target object    
target.id string    
target.kind string    
targetUri string    

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

Member Type Required What it is
alg string    
certbot string    
directory string    
errors list    
errors[] string    
expiresAt string, or number, or null    
hmacKey string    
kid string    
message string    
ok boolean yes  
target object    
target.id string    
target.kind string    
targetUri string    

POST /admin-api/acme/deactivate-account

deactivateAcmeAccount

Deactivate an ACME account (RFC 8555 section 7.3.6)

The account authorizes nothing more — every request it signs is answered unauthorized — exactly as if the client had deactivated it itself. Certificates already issued are untouched; revoke them separately.

Mirrors POST /admin/acme 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
account string yes The account id, from GET /admin-api/acme.

200: The account as it now stands.

Member Type Required What it is
account object    
account.contact list    
account.contact[] string    
account.createdAt string, or number, or null    
account.deactivatedAt string, or number, or null    
account.eabKid string, or null    
account.entry object    
account.entry.id string    
account.entry.kind string    
account.entryUri string, or null    
account.id string    
account.orders integer    
account.status string    
account.thumbprint string    
errors list    
errors[] string    
message string    
ok boolean yes  

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

Member Type Required What it is
account object    
account.contact list    
account.contact[] string    
account.createdAt string, or number, or null    
account.deactivatedAt string, or number, or null    
account.eabKid string, or null    
account.entry object    
account.entry.id string    
account.entry.kind string    
account.entryUri string, or null    
account.id string    
account.orders integer    
account.status string    
account.thumbprint string    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/acme/delete-eab

deleteAcmeEab

Delete an External Account Binding key

Removes the key from its entry. An account it already bound keeps its binding; a key not yet used can no longer bind one.

Mirrors POST /admin/acme 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
kid string yes The key id, from GET /admin-api/acme.

200: The key id that was deleted.

Member Type Required What it is
errors list    
errors[] string    
kid string    
message string    
ok boolean yes  

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

Member Type Required What it is
errors list    
errors[] string    
kid string    
message string    
ok boolean yes  

GET /admin-api/acme/monitor

getAcmeMonitor

What the ACME server has done in this realm

Everything /admin/acme/monitor draws: requests, certificates issued and revoked, refusals, accounts bound, counts by operation, profile, principal, error code and HTTP status, and the most recent requests (paged by page). Per trust realm, merged across processes, and with no reset: the durable record is GET /admin-api/audit.

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

Scope: admin:read.

Parameters

Name In Type Required What it is
page query integer   Which page of the 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 totals, the tables and the recent requests.

Member Type Required What it is
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    
realm 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.accounts integer    
totals.accountsBound integer    
totals.certificatesHeld integer    
totals.issued integer    
totals.refused integer    
totals.requests integer    
totals.revoked integer    

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

removeAcmeHostName

Remove a registered host name from an entry

Certificates already issued for it are untouched; a new order for it is refused rejectedIdentifier.

Mirrors POST /admin/acme 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 registered name to remove.
identifier string yes The username of a person, or the identifier of an application, in this realm.
kind one of person, application yes Whether the entry is a person (ou=users) or an application (ou=applications).

200: The entry’s host names as they now stand.

Member Type Required What it is
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  

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

Member Type Required What it is
entryUri string    
errors list    
errors[] string    
hostNames list    
hostNames[] string    
message string    
ok boolean yes  

POST /admin-api/acme/revoke-certificate

revokeAcmeCertificate

Revoke a certificate issued over ACME

Puts the certificate on the ACME Issuing CA’s CRL (/pki/crl/{realm}/acme) with the RFC 5280 reason given, and its OCSP responder answers revoked. The record on the entry is marked revoked.

Mirrors POST /admin/acme 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 reason; unspecified by default.
serial string yes The serial number in hex.

200: The serial that was revoked, and the reason.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
reason string    
serialHex string    

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

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
reason string    
serialHex string