Management API

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