Management API

The Simple Certificate Enrolment Protocol (RFC 8894) server of this realm: its Issuing CA and RA certificate, the single-use challenge passwords that authorize an enrollment, registered host names, the certificates issued over it, and what it has done.

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

getScep

The SCEP server: endpoints, Issuing CA, RA certificate, profiles, challenges, host names, certificates, settings

Everything /admin/scep draws, out of the same view function: the absolute endpoint URLs of this realm’s SCEP server (RFC 8894) and GetCACaps’ capabilities; the SCEP Issuing CA and whether the hierarchy is built; the RA certificate (subject, serial, key algorithm, expiry, status — never its private key); the nine profiles with what each needs, whether scep.allowedProfiles allows it and its SCEP URL, and the five refused with why; the challenge passwords (paged, credentialsPage; ids and status, never a secret); the registered host names; the certificates issued over SCEP (paged, certificatesPage); the documented exceptions; the mode; and the scep.* 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, for both lists.
certificatesPage query integer   The page of the enrolled certificates.
credentialsPage query integer   The page of the challenge passwords.
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 SCEP server as the page draws it.

Member Type Required What it is
actions list    
actions[] string    
algorithms object    
algorithms.ciphers list    
algorithms.ciphers[] string    
algorithms.digests list    
algorithms.digests[] string    
algorithms.keyTransports list    
algorithms.keyTransports[] string    
algorithms.refusedCiphers list    
algorithms.refusedCiphers[] string    
algorithms.refusedDigests list    
algorithms.refusedDigests[] string    
algorithms.replyCipher string    
algorithms.replyKeyTransport string    
algorithms.replySignature string    
algorithms.signatures list    
algorithms.signatures[] string    
authority object    
authority.certificatePem string    
authority.intermediate object    
authority.intermediate.notAfter string    
authority.intermediate.subject string    
authority.keyAlg string    
authority.notAfter string    
authority.notBefore string    
authority.root object    
authority.root.notAfter string    
authority.root.subject string    
authority.serialHex string    
authority.signatureAlg string    
authority.subject string    
authority.thumbprint string    
authorityNote string    
capabilities list    
capabilities[] 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    
challenges object    
challenges.paging object    
challenges.paging.firstRow integer    
challenges.paging.lastRow integer    
challenges.paging.noun string    
challenges.paging.page integer    
challenges.paging.pages integer    
challenges.paging.param string    
challenges.paging.perPage integer    
challenges.paging.total integer    
challenges.rows list    
challenges.rows[].createdAt string, or number, or null    
challenges.rows[].createdBy string    
challenges.rows[].entry object    
challenges.rows[].entry.id string    
challenges.rows[].entry.kind string    
challenges.rows[].entryUri string    
challenges.rows[].expiresAt string, or number, or null    
challenges.rows[].id string    
challenges.rows[].profile string    
challenges.rows[].status string    
challenges.rows[].url string    
challenges.rows[].usedAt string, or number, or null    
defaultProfile string, or null    
enabled boolean    
endpoints object    
endpoints.cgi string    
endpoints.getCaCaps string    
endpoints.getCaCert string    
endpoints.pkiOperation string    
endpoints.scep string    
exceptions list    
exceptions[].what string    
exceptions[].why string    
hierarchyBuilt boolean    
hostNames list    
hostNames[].entry object    
hostNames[].entry.id string    
hostNames[].entry.kind string    
hostNames[].entryUri string    
hostNames[].hostNames list    
hostNames[].hostNames[] string    
messageTypes map    
messageTypes.{key} string    
mode object    
mode.mode string    
mode.requirement object    
mode.requirement.development string    
mode.requirement.id string    
mode.requirement.product string    
mode.requirement.what string    
mode.requirement.where string    
mode.scep string    
operations list    
operations[] string    
page string    
profiles list    
profiles[].allowed boolean    
profiles[].id string    
profiles[].keys string    
profiles[].needs string    
profiles[].url 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    
ra object    
ra.certificatePem string    
ra.keyAlgorithm string    
ra.notAfter string    
ra.notBefore string    
ra.present boolean    
ra.serialHex string    
ra.status string    
ra.subject string    
ra.thumbprint string    
ra.wantedKeyAlgorithm string    
realm string    
refusedProfiles list    
refusedProfiles[].id string    
refusedProfiles[].why string    
revokeReasons list    
revokeReasons[] 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/scep/add-host-name

addScepHostName

Register a DNS name or IP address on an entry

A dNSName or iPAddress is issued over any enrollment protocol only when it is registered on the entry.

Mirrors POST /admin/scep 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 the application identifier, in this realm.
kind one of person, application yes Whether the entry is a person or an application.

200: The entry’s host names now.

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/scep/create-challenge

createScepChallenge

Create a single-use SCEP challenge password for one entry and one profile

The challenge authorizes ONE enrollment, AS the entry it names, for the profile it names (the default profile when none is given). It is in this reply once and never again: the entry keeps only its SHA-256. The reply also carries the SCEP URL for its profile and a ready-to-paste sscep sequence.

Mirrors POST /admin/scep 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 the application identifier, in this realm.
kind one of person, application yes Whether the entry is a person or an application.
lifetimeS integer   Seconds it may wait, at most scep.challengeLifetimeS.
profile string   One of the nine enrollment profiles.

200: The challenge, once, with its URL.

Member Type Required What it is
challenge string    
entryUri string    
errors list    
errors[] string    
expiresAt string, or number, or null    
hint string    
id string    
message string    
ok boolean yes  
plainUrl string    
profile string    
target object    
target.id string    
target.kind string    
url string    

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

Member Type Required What it is
challenge string    
entryUri string    
errors list    
errors[] string    
expiresAt string, or number, or null    
hint string    
id string    
message string    
ok boolean yes  
plainUrl string    
profile string    
target object    
target.id string    
target.kind string    
url string    

POST /admin-api/scep/delete-challenge

deleteScepChallenge

Delete a SCEP challenge password

The challenge stops being redeemable. A certificate already issued with it is untouched.

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

200: The id that was deleted.

Member Type Required What it is
entryUri string    
errors list    
errors[] string    
id 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    
id string    
message string    
ok boolean yes  

GET /admin-api/scep/monitor

getScepMonitor

What the SCEP server has done: requests, issuances, refusals by failInfo and by error code

Everything /admin/scep/monitor draws: the counters since the process started, per trust realm and added across processes — requests, issued, refused, revoked, challenges created; counts by operation (PKIOperation by messageType), by RFC 8894 failInfo, by STS error code, by profile and by principal; and the recent requests (paged). No reset: the durable record is GET /admin-api/audit.

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

Scope: admin:read.

Parameters

Name In Type Required What it is
per query integer   Rows per page of the recent requests.
page query integer   The page of the recent requests.
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 the recent requests.

Member Type Required What it is
errorCodes map    
errorCodes.{key} number    
failInfo map    
failInfo.{key} number    
issuedCertificates integer    
lastAt string, or number, or null    
operations map    
operations.{key} number    
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 map    
principals.{key} number    
processes integer    
profiles map    
profiles.{key} number    
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 map    
statuses.{key} number    
title string    
totals object    
totals.challengesCreated integer    
totals.issued integer    
totals.refused integer    
totals.requests integer    
totals.revoked integer    

POST /admin-api/scep/reissue-ra

reissueScepRa

Re-issue the SCEP RA certificate

A new RSA key pair (scep.raKeyAlgorithm) certified by the SCEP Issuing CA; the certificate it replaces is put on that CA’s CRL as superseded. Clients encrypting to the old one are answered badMessageCheck until they fetch GetCACert again.

Mirrors POST /admin/scep 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 (optional)

An empty object.

200: The RA certificate as it now stands.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  
ra object    
ra.certificatePem string    
ra.keyAlgorithm string    
ra.notAfter string    
ra.notBefore string    
ra.present boolean    
ra.serialHex string    
ra.status string    
ra.subject string    
ra.thumbprint string    
ra.wantedKeyAlgorithm 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  
ra object    
ra.certificatePem string    
ra.keyAlgorithm string    
ra.notAfter string    
ra.notBefore string    
ra.present boolean    
ra.serialHex string    
ra.status string    
ra.subject string    
ra.thumbprint string    
ra.wantedKeyAlgorithm string    

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

removeScepHostName

Remove a registered host name from an entry

Certificates already issued for it are untouched.

Mirrors POST /admin/scep 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 the application identifier, in this realm.
kind one of person, application yes Whether the entry is a person or an application.

200: The entry’s host names now.

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/scep/revoke-certificate

revokeScepCertificate

Revoke a certificate issued over SCEP

Puts the serial on the SCEP Issuing CA’s CRL and OCSP with the RFC 5280 reason given, and marks the record on the entry revoked.

Mirrors POST /admin/scep 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, affiliationChanged, superseded, cessationOfOperation, privilegeWithdrawn   The RFC 5280 reason.
serial string yes The serial, hexadecimal.

200: The serial and the reason.

Member Type Required What it is
entryUri string    
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
entryUri string    
errors list    
errors[] string    
message string    
ok boolean yes  
reason string    
serialHex string