This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
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 |