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