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/realms
getRealms
Every trust realm, its endpoints and what it sets
A TRUST REALM is a whole logical copy of this service: its own configuration, its own signing key, and its own sessions, authorization codes, tokens, credential offers, service providers, statistics and audit log — answering on the same sockets as every other realm and told apart by a segment at the front of the path.
The DEFAULT realm has no prefix, cannot be removed and cannot be renamed: every URL this service published before realms existed is a URL in it. A process with no realms defined behaves exactly as it did before this feature existed, which is a property of one predicate rather than a claim.
Each row carries the realm’s domain and baseDn, its pathPrefix, its baseUrl, the kid of its signing key — two realms showing one kid would be two names for one authorization server — the settings it sets, and the four discovery documents a client asks for first.
retiring is null, or says the realm is being REMOVED (#262, #294): since and sinceIso, whether the removal is inProgress or was interrupted (the process doing it stopped; every new sign-in and issuance in it is refused until it is finished), refusing, why and finish — for an interrupted one, POST /admin-api/realms/remove again, from another realm.
support is the part answered nowhere else: WHICH protocol families a realm actually separates, which is not a tidy answer. A realm separates what this service ISSUES and everything it holds while issuing it — keys, sessions, codes, tokens, offers, artifacts, statistics and the audit log. It does NOT separate the embedded directory: LDAP answers on a socket with no path to put a segment in, so there is one set of people, groups and applications for the whole process — which means OAuth client registrations, SAML service provider entries, the SPIFFE registry and the two admin console roles are shared. Kerberos, the certificate the main port and LDAPS 636 present, and SPIFFE’s four sockets are shared for the same reason.
reserved is the list of ids a realm may not be called, read off the live router: they are the first segments of paths this service already serves, and the refusal stands whatever realms.pathSegment is set to precisely so that clearing that setting cannot turn an existing realm into a shadow over the console or the authorization server.
Mirrors GET /admin/realms on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
page |
query | integer | Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is. | |
per |
query | integer | Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own. | |
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 realms, and the support table.
| Member | Type | Required | What it is |
|---|---|---|---|
active |
boolean | ||
count |
integer | ||
current |
string | ||
currentName |
string | ||
defaultDomain |
string | ||
enabled |
boolean | ||
paging |
object | Which page of how many, and the query parameter that moves it. | |
paging.firstRow |
integer | ||
paging.lastRow |
integer | ||
paging.noun |
string | ||
paging.page |
integer | ||
paging.pages |
integer | ||
paging.param |
string | ||
paging.perPage |
integer | ||
paging.total |
integer | ||
pathSegment |
string | ||
persistence |
object | ||
persistence.mode |
string | ||
persistence.persistsRealms |
boolean | ||
realms |
list | ||
realms[].baseDn |
string | ||
realms[].baseUrl |
string | ||
realms[].builtin |
boolean | ||
realms[].description |
string, or null | ||
realms[].domain |
string | ||
realms[].endpoints |
object | ||
realms[].endpoints.authorizationServerMetadata |
string | ||
realms[].endpoints.jwks |
string | ||
realms[].endpoints.openidConfiguration |
string | ||
realms[].endpoints.samlMetadata |
string | ||
realms[].id |
string | ||
realms[].kid |
string, or null | ||
realms[].listeners |
list | ||
realms[].listeners[].certificateSource |
string | ||
realms[].listeners[].clientAuth |
string, or null | ||
realms[].listeners[].here |
object | ||
realms[].listeners[].here.boundAt |
string, or number, or null | ||
realms[].listeners[].here.certificate |
object | ||
realms[].listeners[].here.certificate.notAfter |
string | ||
realms[].listeners[].here.certificate.notBefore |
string | ||
realms[].listeners[].here.certificate.serialHex |
string | ||
realms[].listeners[].here.certificate.source |
string | ||
realms[].listeners[].here.hostnames |
list | ||
realms[].listeners[].here.hostnames[] |
string | ||
realms[].listeners[].here.id |
string | ||
realms[].listeners[].here.owner |
string | ||
realms[].listeners[].here.port |
integer | ||
realms[].listeners[].here.publicBaseUrl |
string, or null | ||
realms[].listeners[].here.state |
string | ||
realms[].listeners[].here.why |
string, or null | ||
realms[].listeners[].hostnames |
list | ||
realms[].listeners[].hostnames[] |
string | ||
realms[].listeners[].id |
string | ||
realms[].listeners[].port |
integer | ||
realms[].listeners[].publicBaseUrl |
string, or null | ||
realms[].name |
string | ||
realms[].pathPrefix |
string | ||
realms[].retiring |
object | ||
realms[].retiring.finish |
string | ||
realms[].retiring.finishesBy |
number | ||
realms[].retiring.inProgress |
boolean | ||
realms[].retiring.interrupted |
boolean | ||
realms[].retiring.refusing |
string | ||
realms[].retiring.since |
number | ||
realms[].retiring.sinceIso |
string | ||
realms[].retiring.why |
string | ||
realms[].settings |
list | ||
realms[].settings[].group |
string | ||
realms[].settings[].key |
string | ||
realms[].settings[].label |
string | ||
realms[].settings[].value |
string | ||
reserved |
list | ||
reserved[] |
string | ||
settings |
object | The settings this page draws, described: the same rows GET /config returns, filtered to the ones this page owns. | |
settings.context |
object | ||
settings.context.configFile |
string, or null | ||
settings.context.defaultsFile |
string | ||
settings.context.inRealm |
boolean | ||
settings.context.persistenceMode |
string | ||
settings.context.persistsAppconfig |
boolean | ||
settings.context.persistsRealms |
boolean | ||
settings.context.realmId |
string | ||
settings.editableCount |
integer | How many of them can be changed while the service runs. | |
settings.groups |
list | In the order config.js declares them. |
|
settings.groups[] |
object | One group’s settings. | |
settings.groups[].group |
string | ||
settings.groups[].settings |
list | ||
settings.groups[].settings[] |
object | One setting: what it is, what it is set to, and where that came from. | |
settings.groups[].settings[].appconfigPath |
string | ||
settings.groups[].settings[].csvValueNotes |
map | Present beside csvValues where the setting describes each value: the value mapped to one sentence. |
|
settings.groups[].settings[].csvValueNotes.{key} |
string | ||
settings.groups[].settings[].csvValues |
list | Present on a csv setting whose entries must each be one of these; absent on an open list. |
|
settings.groups[].settings[].csvValues[] |
string | ||
settings.groups[].settings[].default |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].default[] |
string, or number, or boolean | ||
settings.groups[].settings[].description |
string | What it does and why the default is the default. | |
settings.groups[].settings[].editRefusal |
string | Why this row cannot be edited from the realm the reader is in: realms.maxCount while a realm other than the default is ambient. Absent on every row of the default realm’s answer. |
|
settings.groups[].settings[].editable |
boolean | Whether POST /config/set will take it from the realm this answer was read in. False means either the value was consumed at startup or editRefusal is set. It is refused rather than accepted, because an accepted change that does nothing reads as having worked. |
|
settings.groups[].settings[].enumValues |
list | Present on enum settings only. |
|
settings.groups[].settings[].enumValues[] |
string | ||
settings.groups[].settings[].env |
string | Its environment variable. | |
settings.groups[].settings[].group |
string | The protocol it belongs to, and the console’s section heading. | |
settings.groups[].settings[].key |
string | The dot path, which is BOTH the name every operation here takes and the path in the appconfig file. oid4vci.batchSize is appconfig.oid4vci.batchSize. |
|
settings.groups[].settings[].label |
string | ||
settings.groups[].settings[].masked |
boolean | Present, true, when a sensitive value here was replaced. | |
settings.groups[].settings[].max |
number | The highest value it will take. | |
settings.groups[].settings[].min |
number | The lowest value POST /config/set will take, on an int setting that declares one. | |
settings.groups[].settings[].ordered |
boolean | Present, true, on a csv setting whose order is a preference: the first value is the most preferred. |
|
settings.groups[].settings[].overridden |
boolean | Whether a runtime override is in force. Equal to source === "override", and reported separately so a caller can filter without matching a string. |
|
settings.groups[].settings[].realmSettable |
boolean | Whether a trust realm may hold its own value for it. | |
settings.groups[].settings[].restartReason |
string | Why it is not editable, when the value was consumed at startup. | |
settings.groups[].settings[].selectAll |
object | Present on an ordered setting whose select-all is narrowed by other settings. onlyWhileOn: the values are selected only while that setting is on. aloneWhileOn: while that setting is on, only the values are selected. canBeOn is false where this mode never lets that setting be on. |
|
settings.groups[].settings[].selectAll.aloneWhileOn |
list | ||
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.aloneWhileOn[].on |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.aloneWhileOn[].setting |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.aloneWhileOn[].values |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn |
list | ||
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn[].on |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn[].setting |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn[].values |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].source |
one of realm, override, env, env-legacy, appconfig, defaults, default |
Where the effective value came from, highest first: this trust realm’s own value; a runtime override set through this API or the console; the setting’s own environment variable; a legacy variable (no row has one since #523); the appconfig file CONFIG_FILE names; env/defaults.js, the DEFAULT appconfig file that one is unioned on top of. default is the row’s own built-in default, the floor beneath both files: for a DERIVED setting it is a function of a neighbouring setting; for any other it means env/defaults.js lacks the setting (an env/ directory older than the image, which the start warns of as STS-CORE-0177). Only a setting with no default and no value anywhere stops this service from STARTING. |
|
settings.groups[].settings[].step |
number | The value must be a MULTIPLE of this, counted from min. The four token lifetimes use 30. |
|
settings.groups[].settings[].text |
string | The same value on one line: what the console shows in its input and what the environment variable would carry. | |
settings.groups[].settings[].type |
string | How a value posted for it is coerced and checked: one of config.js’s types (string, int, port, bool, csv, enum, color). |
|
settings.groups[].settings[].value |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].value[] |
string, or number, or boolean | ||
settings.overridden |
list | The keys on this page with a runtime override in force. | |
settings.overridden[] |
string | ||
settings.page |
string | ||
settings.setWith |
string | The operation that writes them. | |
settings.settingCount |
integer | ||
settings.sharedWith |
map | A group drawn on another page as well, and those pages. | |
settings.sharedWith.{key} |
list | ||
settings.sharedWith.{key}[].label |
string, or null | ||
settings.sharedWith.{key}[].path |
string | ||
support |
list | ||
support[].by |
string | ||
support[].cards |
list | ||
support[].cards[] |
string | ||
support[].family |
string | ||
support[].note |
string | ||
support[].state |
string |
POST /admin-api/realms/create
createRealm
Define a trust realm
Every HTTP endpoint this service has begins answering under the new realm’s prefix immediately, with a signing key of its own and nothing issued yet.
The id becomes a PATH SEGMENT, so it is lower-case letters, digits and hyphens, starts with a letter or a digit, and is at most 31 characters. It may not be default, and it may not be the first segment of a path this service already serves — GET /admin-api/realms lists those in reserved.
The domain is the realm’s DNS domain — iyasec.io — and it is FIXED from here on. Its directory is a tree of its own at the RFC 2247 mapping of it (dc=iyasec,dc=io), no two realms may share one, and one inside another realm’s is allowed and is a separate tree. Omitted, it is <id>.<global.domain>.
EIGHT SETTINGS ARE SEEDED ON A NEW REALM FROM ITS DOMAIN and they are the ones that are NAMES rather than behaviour: the SAML 2.0 entityID (urn:<domain>:idp), the SAML 1.1 providerID (urn:<domain>:idp:saml11), the WS-Federation entityID, the WS-Trust issuer and the SAML assertion issuer (urn:<domain>:sts), the SPIFFE trust domain (the domain), the Kerberos realm (the domain in capitals), and the OpenID4VP verifier client id (the process’s with the id appended). Two realms carrying one entityID is not a configuration choice — it is two identity providers claiming one name, which a service provider is entitled to refuse. They are ORDINARY settings on the realm: pass overrides to choose your own, or unset them afterwards to go back to sharing the process’s name, which is a case worth being able to build for testing.
The OAuth issuer is deliberately NOT seeded: it defaults to naming the base URL a request arrived on, and that already carries the realm prefix.
Creation is capped by realms.maxCount, which counts the default realm. At the cap the create is refused and nothing is defined. Lowering the cap does not remove realms that already exist. Only a service administrator in the default realm may change the limit.
Mirrors POST /admin/realms 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 |
|---|---|---|---|
description |
string | ||
domain |
string | The realm’s DNS domain, at least two labels. Fixed once the realm exists; defaults to <id>.<global.domain>. |
|
id |
string | yes | Lower-case letters, digits and hyphens. It is the path segment. |
name |
string | What a person calls it. Free text; defaults to the id. | |
overrides |
object | Settings to set on the realm, named by the dot paths GET /admin-api/config lists. They win over the seeded names. Every realms.* key is refused on a realm: one of them decides whether realms exist and where they are found, and a realm carrying it would be changing how it was reached half way through the request that found it. |
200: The realm id, in realm.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
POST /admin-api/realms/remove
removeRealm
Remove a realm, and everything it holds
EVERYTHING IT ACCUMULATED GOES WITH IT: its sessions, its authorization codes, its tokens, its refresh families, its credential offers, its service providers, its statistics, its audit log and its signing key. That is deliberate rather than thorough — a realm re-created with the same id inheriting the last one’s sessions and tokens would be the single most surprising thing a re-created realm could do.
NOTHING IS REMOVED FROM THE DIRECTORY, because nothing there belongs to a realm: ou=users, ou=groups and ou=applications are shared by every realm in this process.
A realm cannot remove ITSELF — a call to /realm/acme/admin-api/realms/remove naming acme is refused. Everything about the removal would work; what would not is the caller, which would be talking to a prefix that had stopped existing. Call it from another realm, or from the default one.
The DEFAULT realm cannot be removed at all.
Mirrors POST /admin/realms 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 |
200: The realm id, in realm.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
POST /admin-api/realms/set
setRealmSetting
Set one setting on one realm
The value applies to the next request that arrives under that realm’s prefix and to nothing else — above whatever the process as a whole is configured with, and below nothing.
This is the same store POST /realm/<id>/admin-api/config/set writes to, and either is fine; the difference is only which realm you have to be in to make the call. A setting whose editable is false is refused with the reason, exactly as it is on the service-wide resource, and every realms.* key is refused outright. realms.maxCount is process-wide; only the default realm’s service administrator changes it, and a create past that limit is refused. Lowering the limit does not remove realms.
Mirrors POST /admin/realms 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 | |
key |
string | yes | |
value |
any JSON | yes |
200: The realm and the key, in realm and key.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
POST /admin-api/realms/unset
unsetRealmSetting
Drop one setting from one realm
The realm falls back to whatever this service as a whole is configured with — which may itself be a runtime override, and is left alone. A key the realm does not set is refused rather than treated as already done, because the two are different facts and a caller that misspelt a key would otherwise be told it succeeded.
Mirrors POST /admin/realms 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 | |
key |
string | yes |
200: The realm and the key, in realm and key.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
POST /admin-api/realms/update
updateRealm
Rename a realm, or describe it
The id cannot be changed, because it is the path segment every client was given. Define a new realm and remove this one if that is what is wanted — and note that the new one gets a new signing key, which is the honest consequence of it being a different realm. The domain is fixed for the same kind of reason: a domain other than the realm’s own is refused (STS-CORE-0101), and the same value again is accepted and changes nothing.
Mirrors POST /admin/realms 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 |
|---|---|---|---|
description |
string | ||
domain |
string | ||
id |
string | yes | |
name |
string |
200: The realm id, in realm.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
bootstrap |
object | ||
bootstrap.created |
boolean | ||
bootstrap.passwordResetRequired |
boolean | ||
bootstrap.username |
string | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
key |
string | ||
message |
string | ||
ok |
boolean | yes | |
password |
string | The bootstrap administrator’s generated password, in product mode, once. | |
prefix |
string | ||
realm |
string | ||
retirement |
object | ||
retirement.boundSeconds |
number | ||
retirement.failed |
list | ||
retirement.failed[] |
string | ||
retirement.late |
list | ||
retirement.late[] |
string | ||
retirement.undelivered |
list | ||
retirement.undelivered[].count |
number | ||
retirement.undelivered[].what |
string | ||
retiring |
object | ||
retiring.finish |
string | ||
retiring.finishesBy |
number | ||
retiring.inProgress |
boolean | ||
retiring.interrupted |
boolean | ||
retiring.refusing |
string | ||
retiring.since |
number | ||
retiring.sinceIso |
string | ||
retiring.why |
string | ||
username |
string |