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/authorization-servers
getAuthorizationServers
Every authorization server profile, and what its document says
One process, several authorization servers. The path component the two discovery shapes already carry — RFC 8414 section 3.1 INSERTS it after the well-known segment, OpenID Connect Discovery section 4 APPENDS the well-known segment to it — now selects a CONFIGURATION as well as an issuer identifier.
A path nobody has configured publishes the document this service always published, so nothing that worked before behaves differently.
Every reply carries drift: the members whose published value disagrees with what this service would publish, and the removals that hide something real. A profile that lies is often exactly what is wanted — it is how you find out whether a client reads the metadata — but a service that let somebody publish a misleading document QUIETLY would be a trap.
?profile=<id> returns one of them with every override, every removal and its drift.
Mirrors GET /admin/authorization-servers on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
profile |
query | string | One profile, by the path component that selects it. Answers 200 with found: false for one that is not configured — whose discovery URLs still answer, with this service’s own document. |
|
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 profiles with the paging that found them, or one profile with its overrides and drift.
| Member | Type | Required | What it is |
|---|---|---|---|
authorizationServers |
list | ||
authorizationServers[].autoCreated |
boolean | ||
authorizationServers[].changedAt |
string | ||
authorizationServers[].createdAt |
string | ||
authorizationServers[].description |
string | ||
authorizationServers[].drift |
list | ||
authorizationServers[].drift[].actual |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
authorizationServers[].drift[].kind |
string | ||
authorizationServers[].drift[].member |
string | ||
authorizationServers[].drift[].published |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
authorizationServers[].drift[].what |
string | ||
authorizationServers[].id |
string | ||
authorizationServers[].label |
string | ||
authorizationServers[].memberCount |
integer | ||
authorizationServers[].overrides |
map | The members this server overrides. | |
authorizationServers[].overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
authorizationServers[].removed |
list | ||
authorizationServers[].removed[] |
string | ||
authorizationServers[].seen |
number | ||
authorizationServers[].seenAt |
string | ||
authorizationServers[].urls |
object | ||
authorizationServers[].urls.authorize |
string | ||
authorizationServers[].urls.oauth |
string | ||
authorizationServers[].urls.oidc |
string | ||
authorizationServers[].urls.token |
string | ||
autoCreated |
boolean | ||
capabilities |
any JSON | The RFC 8414 document this server would publish: what this service builds, with the operator’s overrides, whose values are any JSON. The RFC 8414 document this server would publish: what this service builds, with the operator’s overrides, whose values are any JSON. | |
changedAt |
string | ||
createdAt |
string | ||
description |
string | ||
drift |
list | ||
drift[].actual |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
drift[].kind |
string | ||
drift[].member |
string | ||
drift[].published |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
drift[].what |
string | ||
driftTotal |
integer | ||
firstRow |
integer | ||
found |
boolean | ||
id |
string | ||
label |
string | ||
lastRow |
integer | ||
memberCount |
integer | ||
memberGroups |
list | ||
memberGroups[] |
string | ||
members |
list | ||
members[].document |
string | ||
members[].enforces |
string | ||
members[].group |
string | ||
members[].kind |
string | ||
members[].name |
string | ||
members[].what |
string | ||
overrideTotal |
integer | ||
overrides |
map | The members this server overrides. | |
overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
page |
integer | ||
pages |
integer | ||
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 | ||
perPage |
integer | ||
profileCount |
integer | ||
removed |
list | ||
removed[] |
string | ||
seen |
number | ||
seenAt |
string | ||
shown |
integer | ||
urls |
object | ||
urls.authorize |
string | ||
urls.oauth |
string | ||
urls.oidc |
string | ||
urls.token |
string |
POST /admin-api/authorization-servers/create
createAuthorizationServer
Add an authorization server profile
The id is a single URL path segment, because it has to appear in a discovery URL without being escaped — one that had to be escaped would be one nobody could find again. A new profile has no overrides, so both its documents say exactly what this service says about itself, which is the right place to start from.
Mirrors POST /admin/authorization-servers 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 | Optional note. | |
id |
string | yes | 1-64 characters of letters, digits, dot, dash, underscore or tilde, starting with a letter or a digit. |
label |
string | Optional display name. |
200: The profile and the two URLs it is published at.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
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 | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
string |
POST /admin-api/authorization-servers/delete
deleteAuthorizationServer
Delete a profile
The two discovery URLs go on answering — with this service’s own document and the issuer taken from the path — because an unconfigured path component has always been served that way rather than 404’d.
Mirrors POST /admin/authorization-servers 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 |
|---|---|---|---|
| (the answer) | any JSON |
200: A message saying what still answers.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
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 | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
string |
POST /admin-api/authorization-servers/remove
removeAuthorizationServerMember
Stop publishing a member at all
DIFFERENT FROM reset, and the difference is the reason both exist: reset undoes an override and this publishes an ABSENCE. A client that cannot find code_challenge_methods_supported does not learn that PKCE is unavailable — it learns nothing, and RFC 9700 section 2.6 is entirely about that difference.
Mirrors POST /admin/authorization-servers 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 |
|---|---|---|---|
| (the answer) | any JSON |
200: The profile as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
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 | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
string |
POST /admin-api/authorization-servers/reset
resetAuthorizationServerMember
Put one member back to what this service publishes
Undoes an override or a removal for a single member, leaving the rest of the profile alone.
Mirrors POST /admin/authorization-servers 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 |
|---|---|---|---|
| (the answer) | any JSON |
200: The profile as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
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 | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
string |
POST /admin-api/authorization-servers/set
setAuthorizationServerMember
Publish a metadata member with a chosen value
The value is read as JSON first and as a plain string if that fails, so ["S256"] is a list, false is a boolean and https://example.com/token is a string.
Any member name is accepted, including one this service has never heard of; the catalogue in the GET reply is help for whoever fills the form rather than a constraint. A member that is also removed stops being removed, or the call would appear to do nothing.
What this does NOT change is what the endpoints do. Advertise code_challenge_methods_supported: ["plain"] and the token endpoint still verifies S256 — which is the point, and is reported as drift rather than left to be discovered.
Mirrors POST /admin/authorization-servers 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 |
|---|---|---|---|
| (the answer) | any JSON |
200: The profile as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
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 | |
profile |
object | ||
profile.autoCreated |
boolean | ||
profile.changedAt |
string | ||
profile.createdAt |
string | ||
profile.description |
string | ||
profile.id |
string | ||
profile.label |
string | ||
profile.memberCount |
integer | ||
profile.overrides |
map | The members this server overrides. | |
profile.overrides.{key} |
any JSON | An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. An RFC 8414 metadata member’s value as the operator chose to publish it: any JSON, deliberately, including what no specification defines. | |
profile.removed |
list | ||
profile.removed[] |
string | ||
profile.seen |
number | ||
profile.seenAt |
string | ||
profile.urls |
object | ||
profile.urls.authorize |
string | ||
profile.urls.oauth |
string | ||
profile.urls.oidc |
string | ||
profile.urls.token |
string |