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/claim-providers
getClaimProviders
The Claims Providers this realm aggregates claims from, and every person’s link (OIDC Core 5.6.2)
Everything /admin/claim-providers draws: each registered provider (issuer, endpoints, client, the claims it supplies, aggregated or distributed, whether a secret is held), the redirect URI to register at a provider, and every link a person made (their subject there, when, the token’s expiry, whether it is stale). Never a secret or a token.
Mirrors GET /admin/claim-providers 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 |
|---|---|---|---|---|
providersPage |
query | integer | Which page of the providers. Clamped, like every page parameter here. | |
linkq |
query | string | Narrows the links to those whose person, provider or subject there contains this. | |
linksPage |
query | integer | Which page of the matched links. It shares per with the providers. |
|
per |
query | integer | Rows per page of each list, capped. | |
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 register and the links.
| Member | Type | Required | What it is |
|---|---|---|---|
callbackPath |
string | ||
counts |
object | ||
counts.links |
integer | ||
counts.providers |
integer | ||
filter |
object | ||
filter.links |
string, or null | ||
links |
list | ||
links[].expiresAt |
number | ||
links[].linkedAt |
number | ||
links[].provider |
string | ||
links[].refreshable |
boolean | ||
links[].stale |
boolean | ||
links[].sub |
string | ||
links[].username |
string | ||
matched |
object | ||
matched.links |
integer | ||
paging |
object | ||
paging.links |
object | ||
paging.links.firstRow |
integer | ||
paging.links.lastRow |
integer | ||
paging.links.noun |
string | ||
paging.links.page |
integer | ||
paging.links.pages |
integer | ||
paging.links.param |
string | ||
paging.links.perPage |
integer | ||
paging.links.total |
integer | ||
paging.providers |
object | ||
paging.providers.firstRow |
integer | ||
paging.providers.lastRow |
integer | ||
paging.providers.noun |
string | ||
paging.providers.page |
integer | ||
paging.providers.pages |
integer | ||
paging.providers.param |
string | ||
paging.providers.perPage |
integer | ||
paging.providers.total |
integer | ||
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 | ||
providers |
list | ||
providers[].authMethod |
string | ||
providers[].authorizationEndpoint |
string | ||
providers[].claims |
list | ||
providers[].claims[] |
string | ||
providers[].claimsEndpoint |
string | ||
providers[].clientId |
string | ||
providers[].createdAt |
number | ||
providers[].delivery |
string | ||
providers[].hasSecret |
boolean | ||
providers[].id |
string | ||
providers[].issuer |
string | ||
providers[].jwksUri |
string | ||
providers[].name |
string | ||
providers[].scope |
string | ||
providers[].tokenEndpoint |
string | ||
providers[].updatedAt |
number | ||
redirectUri |
string |
POST /admin-api/claim-providers/add-provider
addClaimProvider
Register a Claims Provider
A provider this realm aggregates claims from. discover fills the endpoints left empty from the issuer’s discovery document; the secret is sealed. Audited.
Mirrors POST /admin/claim-providers 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 |
|---|---|---|---|
authMethod |
one of client_secret_basic, client_secret_post, none |
||
authorizationEndpoint |
string | ||
claims |
list | yes | The claim names it supplies. |
claims[] |
string | ||
claimsEndpoint |
string | Its UserInfo endpoint. | |
clientId |
string | yes | This realm’s client_id at the provider. |
clientSecret |
string | Sealed where keys persist; never returned. | |
delivery |
one of aggregated, distributed |
||
discover |
boolean | Fill the endpoints left empty from the issuer’s discovery document. | |
id |
string | yes | The provider’s id in this realm, its _claim_sources key. |
issuer |
string | yes | Its OpenID Provider issuer. |
jwksUri |
string | ||
name |
string | ||
scope |
string | ||
tokenEndpoint |
string |
200: What was registered.
| Member | Type | Required | What it is |
|---|---|---|---|
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 |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/claim-providers/remove-provider
removeClaimProvider
Remove a Claims Provider
It leaves the register; people’s links to it stay on their entries and are never used. Audited.
Mirrors POST /admin/claim-providers on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
id |
string | yes | The provider’s id in this realm, its _claim_sources key. |
200: What was removed.
| Member | Type | Required | What it is |
|---|---|---|---|
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 |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/claim-providers/revoke-link
revokeClaimSourceLink
Revoke a person’s link to a Claims Provider
Their tokens at that provider are removed from their entry, so its claims are no longer sent. Audited.
Mirrors POST /admin/claim-providers 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 |
|---|---|---|---|
provider |
string | yes | The provider’s id in this realm, its _claim_sources key. |
username |
string | yes |
200: What was revoked.
| Member | Type | Required | What it is |
|---|---|---|---|
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 |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/claim-providers/update-provider
updateClaimProvider
Change a Claims Provider
The members given replace the provider’s; the secret is kept unless one is given. Audited.
Mirrors POST /admin/claim-providers 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 |
|---|---|---|---|
authMethod |
one of client_secret_basic, client_secret_post, none |
||
authorizationEndpoint |
string | ||
claims |
list | The claim names it supplies. | |
claims[] |
string | ||
claimsEndpoint |
string | Its UserInfo endpoint. | |
clientId |
string | This realm’s client_id at the provider. | |
clientSecret |
string | Sealed where keys persist; never returned. | |
delivery |
one of aggregated, distributed |
||
discover |
boolean | Fill the endpoints left empty from the issuer’s discovery document. | |
id |
string | yes | The provider’s id in this realm, its _claim_sources key. |
issuer |
string | Its OpenID Provider issuer. | |
jwksUri |
string | ||
name |
string | ||
scope |
string | ||
tokenEndpoint |
string |
200: What changed.
| Member | Type | Required | What it is |
|---|---|---|---|
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 |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
GET /admin-api/commands
getProviderCommands
OpenID Provider Commands: the clients, the account register, the tenant runs and the deliveries
Everything /admin/commands draws: whether commands and automatic commands are on, the issuer Command Tokens name, each client with a command_endpoint and what its metadata answer said it supports, the account-state register (what each relying party said about each person), the tenant runs, and the command deliveries. state and q narrow the deliveries. Never a token.
Mirrors GET /admin/commands 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 |
|---|---|---|---|---|
clientsPage |
query | integer | Which page of clients. Each list moves on its own parameter and they share per. |
|
accountsPage |
query | integer | Which page of accounts. Each list moves on its own parameter and they share per. |
|
runsPage |
query | integer | Which page of runs. Each list moves on its own parameter and they share per. |
|
deliveriesPage |
query | integer | Which page of deliveries. Each list moves on its own parameter and they share per. |
|
state |
query | string | Only deliveries in this state: pending, sent or dead. | |
q |
query | string | Narrows the deliveries. | |
per |
query | integer | Rows per page of each list, capped. | |
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 report.
| Member | Type | Required | What it is |
|---|---|---|---|
accountCommands |
list | ||
accountCommands[] |
string | ||
accounts |
list | ||
accounts[].audSub |
string | ||
accounts[].clientId |
string | ||
accounts[].lastAccess |
string, or number | ||
accounts[].lastCommand |
string | ||
accounts[].state |
string | ||
accounts[].sub |
string | ||
accounts[].updatedAt |
string | ||
accounts[].username |
string | ||
automatic |
boolean | ||
clientIds |
list | ||
clientIds[] |
string | ||
clients |
list | ||
clients[].clientId |
string | ||
clients[].endpoint |
string | ||
clients[].learned |
object | ||
clients[].learned.audSubRequired |
boolean | ||
clients[].learned.commandsSupported |
list | ||
clients[].learned.commandsSupported[] |
string | ||
clients[].learned.learnedAt |
string | ||
clients[].learned.roles |
list | ||
clients[].learned.roles[].description |
string | ||
clients[].learned.roles[].display |
string | ||
clients[].learned.roles[].id |
string | ||
clients[].name |
string | ||
counts |
object | ||
counts.dead |
integer | ||
counts.pending |
integer | ||
counts.sent |
integer | ||
deliveries |
list | ||
deliveries[].accountState |
string | ||
deliveries[].attempts |
number | ||
deliveries[].awaitingCallback |
boolean | ||
deliveries[].clientId |
string | ||
deliveries[].command |
string | ||
deliveries[].errorCode |
string | ||
deliveries[].finishedAt |
string | ||
deliveries[].generation |
number | ||
deliveries[].holder |
string | ||
deliveries[].id |
string | ||
deliveries[].inFlight |
boolean | ||
deliveries[].lastAttemptAt |
string | ||
deliveries[].nextAttemptAt |
string | ||
deliveries[].queuedAt |
string | ||
deliveries[].realm |
string | ||
deliveries[].state |
string | ||
deliveries[].status |
number, or string | ||
deliveries[].sub |
string | ||
deliveries[].trigger |
string | ||
deliveries[].uri |
string | ||
deliveries[].username |
string | ||
deliveries[].why |
string | ||
enabled |
boolean | ||
issuer |
string | ||
listCounts |
object | ||
listCounts.accounts |
integer | ||
listCounts.clients |
integer | ||
listCounts.deliveries |
integer | ||
listCounts.runs |
integer | ||
paging |
object | ||
paging.accounts |
object | ||
paging.accounts.firstRow |
integer | ||
paging.accounts.lastRow |
integer | ||
paging.accounts.noun |
string | ||
paging.accounts.page |
integer | ||
paging.accounts.pages |
integer | ||
paging.accounts.param |
string | ||
paging.accounts.perPage |
integer | ||
paging.accounts.total |
integer | ||
paging.clients |
object | ||
paging.clients.firstRow |
integer | ||
paging.clients.lastRow |
integer | ||
paging.clients.noun |
string | ||
paging.clients.page |
integer | ||
paging.clients.pages |
integer | ||
paging.clients.param |
string | ||
paging.clients.perPage |
integer | ||
paging.clients.total |
integer | ||
paging.deliveries |
object | ||
paging.deliveries.firstRow |
integer | ||
paging.deliveries.lastRow |
integer | ||
paging.deliveries.noun |
string | ||
paging.deliveries.page |
integer | ||
paging.deliveries.pages |
integer | ||
paging.deliveries.param |
string | ||
paging.deliveries.perPage |
integer | ||
paging.deliveries.total |
integer | ||
paging.runs |
object | ||
paging.runs.firstRow |
integer | ||
paging.runs.lastRow |
integer | ||
paging.runs.noun |
string | ||
paging.runs.page |
integer | ||
paging.runs.pages |
integer | ||
paging.runs.param |
string | ||
paging.runs.perPage |
integer | ||
paging.runs.total |
integer | ||
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 | ||
runs |
list | ||
runs[].accounts |
number | ||
runs[].actor |
string | ||
runs[].clientId |
string | ||
runs[].command |
string | ||
runs[].errors |
list | ||
runs[].errors[] |
string | ||
runs[].events |
number | ||
runs[].finishedAt |
string | ||
runs[].id |
string | ||
runs[].lastEventId |
string | ||
runs[].resumes |
number | ||
runs[].startedAt |
string | ||
runs[].state |
string | ||
runs[].totalAccounts |
number, or null | ||
runs[].uri |
string | ||
runs[].why |
string | ||
tenantCommands |
list | ||
tenantCommands[] |
string |
POST /admin-api/commands/retry-delivery
retryCommandDelivery
Retry a dead command delivery
A new generation: a fresh attempt budget and the client’s current command_endpoint. Audited.
Mirrors POST /admin/commands 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 |
|---|---|---|---|
delivery |
string | yes |
200: The delivery queued again.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
row |
object | ||
row.accountState |
string | ||
row.attempts |
number | ||
row.awaitingCallback |
boolean | ||
row.clientId |
string | ||
row.command |
string | ||
row.finishedAt |
string | ||
row.generation |
number | ||
row.holder |
string | ||
row.id |
string | ||
row.inFlight |
boolean | ||
row.lastAttemptAt |
string | ||
row.nextAttemptAt |
string | ||
row.queuedAt |
string | ||
row.realm |
string | ||
row.state |
string | ||
row.status |
number, or string | ||
row.sub |
string | ||
row.trigger |
string | ||
row.uri |
string | ||
row.username |
string | ||
row.why |
string | ||
run |
object | ||
run.accounts |
number | ||
run.actor |
string | ||
run.clientId |
string | ||
run.command |
string | ||
run.errors |
list | ||
run.errors[] |
string | ||
run.events |
number | ||
run.finishedAt |
string | ||
run.id |
string | ||
run.lastEventId |
string | ||
run.resumes |
number | ||
run.startedAt |
string | ||
run.state |
string | ||
run.totalAccounts |
number, or null | ||
run.uri |
string | ||
run.why |
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 | |
row |
object | ||
row.accountState |
string | ||
row.attempts |
number | ||
row.awaitingCallback |
boolean | ||
row.clientId |
string | ||
row.command |
string | ||
row.finishedAt |
string | ||
row.generation |
number | ||
row.holder |
string | ||
row.id |
string | ||
row.inFlight |
boolean | ||
row.lastAttemptAt |
string | ||
row.nextAttemptAt |
string | ||
row.queuedAt |
string | ||
row.realm |
string | ||
row.state |
string | ||
row.status |
number, or string | ||
row.sub |
string | ||
row.trigger |
string | ||
row.uri |
string | ||
row.username |
string | ||
row.why |
string | ||
run |
object | ||
run.accounts |
number | ||
run.actor |
string | ||
run.clientId |
string | ||
run.command |
string | ||
run.errors |
list | ||
run.errors[] |
string | ||
run.events |
number | ||
run.finishedAt |
string | ||
run.id |
string | ||
run.lastEventId |
string | ||
run.resumes |
number | ||
run.startedAt |
string | ||
run.state |
string | ||
run.totalAccounts |
number, or null | ||
run.uri |
string | ||
run.why |
string |
POST /admin-api/commands/send-account
sendAccountCommand
Send an account command about one person
One of activate, maintain, suspend, reactivate, archive, restore, delete, audit, invalidate or migrate — or its _async variant — to the client’s command_endpoint, queued on the shared outbound queue. The answer is recorded in the account register. Audited.
Mirrors POST /admin/commands 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 |
|---|---|---|---|
clientId |
string | yes | |
command |
one of activate, maintain, suspend, reactivate, archive, restore, delete, audit, invalidate, migrate, activate_async, maintain_async, suspend_async, reactivate_async, archive_async, restore_async, delete_async, audit_async, invalidate_async, migrate_async |
yes | |
username |
string | yes |
200: The delivery queued.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
row |
object | ||
row.accountState |
string | ||
row.attempts |
number | ||
row.awaitingCallback |
boolean | ||
row.clientId |
string | ||
row.command |
string | ||
row.finishedAt |
string | ||
row.generation |
number | ||
row.holder |
string | ||
row.id |
string | ||
row.inFlight |
boolean | ||
row.lastAttemptAt |
string | ||
row.nextAttemptAt |
string | ||
row.queuedAt |
string | ||
row.realm |
string | ||
row.state |
string | ||
row.status |
number, or string | ||
row.sub |
string | ||
row.trigger |
string | ||
row.uri |
string | ||
row.username |
string | ||
row.why |
string | ||
run |
object | ||
run.accounts |
number | ||
run.actor |
string | ||
run.clientId |
string | ||
run.command |
string | ||
run.errors |
list | ||
run.errors[] |
string | ||
run.events |
number | ||
run.finishedAt |
string | ||
run.id |
string | ||
run.lastEventId |
string | ||
run.resumes |
number | ||
run.startedAt |
string | ||
run.state |
string | ||
run.totalAccounts |
number, or null | ||
run.uri |
string | ||
run.why |
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 | |
row |
object | ||
row.accountState |
string | ||
row.attempts |
number | ||
row.awaitingCallback |
boolean | ||
row.clientId |
string | ||
row.command |
string | ||
row.finishedAt |
string | ||
row.generation |
number | ||
row.holder |
string | ||
row.id |
string | ||
row.inFlight |
boolean | ||
row.lastAttemptAt |
string | ||
row.nextAttemptAt |
string | ||
row.queuedAt |
string | ||
row.realm |
string | ||
row.state |
string | ||
row.status |
number, or string | ||
row.sub |
string | ||
row.trigger |
string | ||
row.uri |
string | ||
row.username |
string | ||
row.why |
string | ||
run |
object | ||
run.accounts |
number | ||
run.actor |
string | ||
run.clientId |
string | ||
run.command |
string | ||
run.errors |
list | ||
run.errors[] |
string | ||
run.events |
number | ||
run.finishedAt |
string | ||
run.id |
string | ||
run.lastEventId |
string | ||
run.resumes |
number | ||
run.startedAt |
string | ||
run.state |
string | ||
run.totalAccounts |
number, or null | ||
run.uri |
string | ||
run.why |
string |
POST /admin-api/commands/send-tenant
sendTenantCommand
Send a tenant command
metadata (a JSON answer, recorded as what the client supports), or one of audit_tenant, suspend_tenant, archive_tenant, delete_tenant and invalidate_tenant (a Server-Sent Events stream, read in the background as a run). Audited.
Mirrors POST /admin/commands 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 |
|---|---|---|---|
clientId |
string | yes | |
command |
one of metadata, audit_tenant, suspend_tenant, archive_tenant, delete_tenant, invalidate_tenant |
yes |
200: The delivery or run started.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
row |
object | ||
row.accountState |
string | ||
row.attempts |
number | ||
row.awaitingCallback |
boolean | ||
row.clientId |
string | ||
row.command |
string | ||
row.finishedAt |
string | ||
row.generation |
number | ||
row.holder |
string | ||
row.id |
string | ||
row.inFlight |
boolean | ||
row.lastAttemptAt |
string | ||
row.nextAttemptAt |
string | ||
row.queuedAt |
string | ||
row.realm |
string | ||
row.state |
string | ||
row.status |
number, or string | ||
row.sub |
string | ||
row.trigger |
string | ||
row.uri |
string | ||
row.username |
string | ||
row.why |
string | ||
run |
object | ||
run.accounts |
number | ||
run.actor |
string | ||
run.clientId |
string | ||
run.command |
string | ||
run.errors |
list | ||
run.errors[] |
string | ||
run.events |
number | ||
run.finishedAt |
string | ||
run.id |
string | ||
run.lastEventId |
string | ||
run.resumes |
number | ||
run.startedAt |
string | ||
run.state |
string | ||
run.totalAccounts |
number, or null | ||
run.uri |
string | ||
run.why |
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 | |
row |
object | ||
row.accountState |
string | ||
row.attempts |
number | ||
row.awaitingCallback |
boolean | ||
row.clientId |
string | ||
row.command |
string | ||
row.finishedAt |
string | ||
row.generation |
number | ||
row.holder |
string | ||
row.id |
string | ||
row.inFlight |
boolean | ||
row.lastAttemptAt |
string | ||
row.nextAttemptAt |
string | ||
row.queuedAt |
string | ||
row.realm |
string | ||
row.state |
string | ||
row.status |
number, or string | ||
row.sub |
string | ||
row.trigger |
string | ||
row.uri |
string | ||
row.username |
string | ||
row.why |
string | ||
run |
object | ||
run.accounts |
number | ||
run.actor |
string | ||
run.clientId |
string | ||
run.command |
string | ||
run.errors |
list | ||
run.errors[] |
string | ||
run.events |
number | ||
run.finishedAt |
string | ||
run.id |
string | ||
run.lastEventId |
string | ||
run.resumes |
number | ||
run.startedAt |
string | ||
run.state |
string | ||
run.totalAccounts |
number, or null | ||
run.uri |
string | ||
run.why |
string |
GET /admin-api/grants
getGrants
The OAuth grants this realm holds (Grant Management for OAuth 2.0)
Everything /admin/grants draws: every grant a client created, merged or replaced through Grant Management, newest first — its grant_id, client, subject and generation, the grant resource the grant management API answers (scopes and resources, claims, authorization_details, created_at, last_updated, expires_at, updated_by) and how many tokens minted under it this realm still records. Never a token.
Mirrors GET /admin/grants on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
client_id |
query | string | Only this client’s grants. | |
grantq |
query | string | Narrows the grants to those whose grant_id, client or subject contains this. | |
grantsPage |
query | integer | Which page of the matched grants. Clamped, like every page parameter here. | |
per |
query | integer | Grants per page, capped. | |
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 grants.
| Member | Type | Required | What it is |
|---|---|---|---|
filter |
object | ||
filter.clientId |
string, or null | ||
filter.q |
string, or null | ||
grants |
list | ||
grants[].authorization_details |
list | ||
grants[].authorization_details[] |
any JSON | An RFC 9396 authorization detail as the client asked for it: a type’s fields are that type’s definition’s, written by an operator. An RFC 9396 authorization detail as the client asked for it: a type’s fields are that type’s definition’s, written by an operator. | |
grants[].claims |
list | ||
grants[].claims[] |
string | ||
grants[].clientId |
list, or string, or number, or boolean, or null | ||
grants[].clientId[] |
string, or number, or boolean | ||
grants[].created_at |
number | ||
grants[].expires_at |
number | ||
grants[].generation |
number | ||
grants[].grantId |
string | ||
grants[].last_updated |
number | ||
grants[].scopes |
list | ||
grants[].scopes[].resource |
list | ||
grants[].scopes[].resource[] |
string | ||
grants[].scopes[].scope |
string | ||
grants[].subject |
list, or string, or number, or boolean, or null | ||
grants[].subject[] |
string, or number, or boolean | ||
grants[].tokens |
integer | ||
grants[].updated_by |
list, or string, or number, or boolean, or null | ||
grants[].updated_by[] |
string, or number, or boolean | ||
matched |
integer | ||
paging |
object | ||
paging.grants |
object | ||
paging.grants.firstRow |
integer | ||
paging.grants.lastRow |
integer | ||
paging.grants.noun |
string | ||
paging.grants.page |
integer | ||
paging.grants.pages |
integer | ||
paging.grants.param |
string | ||
paging.grants.perPage |
integer | ||
paging.grants.total |
integer | ||
total |
integer |
POST /admin-api/grants/revoke-grant
revokeGrant
Revoke a grant
What a client’s DELETE /oauth2/grants/{grant_id} does, done by an administrator: the grant leaves the register, so every refresh token issued under it is refused, and every token this realm recorded under it is revoked. Audited.
Mirrors POST /admin/grants 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 |
|---|---|---|---|
grantId |
string | yes | The grant_id, as GET /admin-api/grants lists it. |
200: How many tokens were revoked with it.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
revoked |
integer |
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 | |
revoked |
integer |
GET /admin-api/oauth2
getOauth2Settings
The authorization server’s own settings
The oauth2.* settings: the issuer identifier, RFC 9700 mode, OAuth 2.1 mode (oauth2.oauth21, draft-ietf-oauth-v2-1-16, which implies RFC 9700 mode), the registered redirect URIs and the loopback port wildcard, Front-Channel Logout, the refresh token idle timeout, whether a sign-out revokes refresh tokens, the client assertion clock skew, the four lifetimes GET /token-lifetimes also reports — and oauth2.breakIdTokenNonce, which makes this service return an ID Token whose nonce is WRONG so that a client can be shown to check it — in development mode only; a product realm ignores it and refuses setting it.
oauth2.rfc9700 is restart-only and says so in restartReason: global.https derives from it and a listener’s scheme is settled when the socket is bound. A TRUST REALM can carry it while the process does not, which is how one process answers permissively at /oauth2/authorize and enforces the BCP under a realm prefix.
THERE IS NO POST BESIDE THIS ONE and that is not a gap: every form on the console page this mirrors posts set-many to /admin/config, so POST /admin-api/config/set-many is already the operation for it. One store, one action, two doors.
Mirrors GET /admin/oauth2 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 |
|---|---|---|---|---|
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: What the page says, and the settings it draws — described rows carrying each value’s source and whether it can be changed while the service runs.
| Member | Type | Required | What it is |
|---|---|---|---|
alsoHtml |
list | ||
alsoHtml[] |
string | ||
leadHtml |
string | ||
links |
list | ||
links[].href |
string | ||
links[].what |
string | ||
notes |
list | ||
notes[] |
string | ||
page |
string | ||
protocolEndpoints |
list | ||
protocolEndpoints[].listening |
boolean | ||
protocolEndpoints[].methods |
list, or string | ||
protocolEndpoints[].methods[] |
string | ||
protocolEndpoints[].name |
string | ||
protocolEndpoints[].registered |
boolean | ||
protocolEndpoints[].route |
string | ||
protocolEndpoints[].transport |
string | ||
protocolEndpoints[].url |
string | ||
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 | The sentence beside each of a list’s values. | |
settings.groups[].settings[].csvValueNotes.{key} |
string | ||
settings.groups[].settings[].csvValues |
list | ||
settings.groups[].settings[].csvValues[] |
string | ||
settings.groups[].settings[].default |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].default[] |
string | ||
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 | ||
settings.groups[].settings[].env |
string, or null | ||
settings.groups[].settings[].group |
string | ||
settings.groups[].settings[].key |
string | ||
settings.groups[].settings[].label |
string | ||
settings.groups[].settings[].legacyEnv |
string, or null | ||
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[].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 |
string | ||
settings.groups[].settings[].step |
number | ||
settings.groups[].settings[].text |
string | ||
settings.groups[].settings[].type |
string | ||
settings.groups[].settings[].value |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].value[] |
string | ||
settings.overridden |
list | ||
settings.overridden[] |
string | ||
settings.page |
string | ||
settings.setWith |
string | ||
settings.settingCount |
integer | ||
settings.sharedWith |
map | The other pages each settings group is drawn on. | |
settings.sharedWith.{key} |
list | ||
settings.sharedWith.{key}[].label |
string | ||
settings.sharedWith.{key}[].path |
string | ||
title |
string | ||
what |
string |
GET /admin-api/oauth2/monitor
getOauth2Monitor
What the authorization server has done in this realm, by mechanism, with the pushed authorization requests still held
Everything /admin/oauth2/monitor draws, in SECTIONS — one per mechanism counted, RFC 9126 pushed authorization requests the first. Each section carries its events (the closed vocabulary with a label and a total each), the totals, the OAuth errors returned, one row per client_id with every counter (paged by clientsPage and per), and — for RFC 9126 — the pushed requests the store still holds, newest first: the digest of the request_uri (its handle; the request_uri itself is not kept), client, authorization server, state, created and expiry, reads, whether and how the client authenticated, form or request object, the redirect_uri and whether section 2.4 let it in unregistered, the DPoP key, and the parameters. That list is paged by offset and limit (or the console’s page and per) and filtered by state and client_id. RFC 9470’s step-up is the second section (stepup), its clients paged by stepUpClientsPage, carrying the requirement this service’s own resource server enforces (ownResourceRequirement) and acrValuesSupported. Per trust realm, merged across processes, and with no reset.
Mirrors GET /admin/oauth2/monitor on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
offset |
query | integer | Skip this many pushed requests (newest first). Wins over page when both are sent. |
|
limit |
query | integer | At most this many pushed requests; 50 by default. | |
state |
query | one of live, spent, all |
live (not yet spent), spent (an authorization response was issued on it; kept until it would have expired), or all, the default. |
|
client_id |
query | string | Only the pushed requests bound to this client. | |
page |
query | integer | The console’s spelling: which page of pushed requests, per to a page. |
|
per |
query | integer | Rows per page, for page and clientsPage. |
|
clientsPage |
query | integer | Which page of the RFC 9126 section’s per-client counter rows. | |
stepUpClientsPage |
query | integer | Which page of the RFC 9470 section’s per-client counter rows. | |
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 sections, their counters and the pushed requests held.
| Member | Type | Required | What it is |
|---|---|---|---|
actions |
list | ||
actions[] |
string | ||
page |
string | ||
sections |
list | ||
sections[].acrValuesSupported |
list | ||
sections[].acrValuesSupported[] |
string | ||
sections[].clients |
list | ||
sections[].clients[].client_id |
string | ||
sections[].clients[].counters |
map | Each counter, for this client. | |
sections[].clients[].counters.{key} |
integer | ||
sections[].clients[].errors |
list | ||
sections[].clients[].errors[].count |
integer | ||
sections[].clients[].errors[].name |
string | ||
sections[].clients[].lastAt |
string, or null | ||
sections[].clients[].lastEvent |
string, or null | ||
sections[].clientsPaging |
object | ||
sections[].clientsPaging.firstRow |
integer | ||
sections[].clientsPaging.lastRow |
integer | ||
sections[].clientsPaging.noun |
string | ||
sections[].clientsPaging.page |
integer | ||
sections[].clientsPaging.pages |
integer | ||
sections[].clientsPaging.param |
string | ||
sections[].clientsPaging.perPage |
integer | ||
sections[].clientsPaging.total |
integer | ||
sections[].clientsParam |
string | ||
sections[].errors |
list | ||
sections[].errors[].count |
integer | ||
sections[].errors[].name |
string | ||
sections[].events |
list | ||
sections[].events[].count |
integer | ||
sections[].events[].counter |
string | ||
sections[].events[].event |
string | ||
sections[].events[].label |
string | ||
sections[].id |
string | ||
sections[].lastAt |
string, or null | ||
sections[].lastEvent |
string, or null | ||
sections[].ownResourceRequirement |
object | ||
sections[].ownResourceRequirement.acr_values |
string, or null | ||
sections[].ownResourceRequirement.max_age |
number, or null | ||
sections[].pushedRequests |
object | ||
sections[].pushedRequests.capacity |
number | ||
sections[].pushedRequests.filter |
object | ||
sections[].pushedRequests.filter.client_id |
string | ||
sections[].pushedRequests.filter.state |
string | ||
sections[].pushedRequests.items |
list | ||
sections[].pushedRequests.items[].attested_jkt |
string | ||
sections[].pushedRequests.items[].authentication_method |
string | ||
sections[].pushedRequests.items[].authorization_server |
list, or string, or number, or boolean, or null | ||
sections[].pushedRequests.items[].authorization_server[] |
string, or number, or boolean | ||
sections[].pushedRequests.items[].client_authenticated |
boolean | ||
sections[].pushedRequests.items[].client_id |
list, or string, or number, or boolean, or null | ||
sections[].pushedRequests.items[].client_id[] |
string, or number, or boolean | ||
sections[].pushedRequests.items[].created_at |
string | ||
sections[].pushedRequests.items[].dpop_jkt |
string | ||
sections[].pushedRequests.items[].expires_at |
string | ||
sections[].pushedRequests.items[].expires_in |
integer | ||
sections[].pushedRequests.items[].parameters |
any JSON | The authorization request a client pushed (RFC 9126), which may carry any parameter and a request object’s claims of any JSON type. The authorization request a client pushed (RFC 9126), which may carry any parameter and a request object’s claims of any JSON type. | |
sections[].pushedRequests.items[].reads |
integer | ||
sections[].pushedRequests.items[].redirect_uri |
string | ||
sections[].pushedRequests.items[].redirect_uri_unregistered |
boolean | ||
sections[].pushedRequests.items[].request_object_alg |
list, or string, or number, or boolean, or null | ||
sections[].pushedRequests.items[].request_object_alg[] |
string, or number, or boolean | ||
sections[].pushedRequests.items[].request_object_encrypted |
list, or string, or number, or boolean, or null | ||
sections[].pushedRequests.items[].request_object_encrypted[] |
string, or number, or boolean | ||
sections[].pushedRequests.items[].request_uri_digest |
string | ||
sections[].pushedRequests.items[].request_uri_shown |
string | ||
sections[].pushedRequests.items[].response_type |
string | ||
sections[].pushedRequests.items[].scope |
string | ||
sections[].pushedRequests.items[].source |
list, or string, or number, or boolean, or null | ||
sections[].pushedRequests.items[].source[] |
string, or number, or boolean | ||
sections[].pushedRequests.items[].spent_at |
string, or null | ||
sections[].pushedRequests.items[].state |
string | ||
sections[].pushedRequests.lifetime_s |
number | ||
sections[].pushedRequests.limit |
integer | ||
sections[].pushedRequests.offset |
integer | ||
sections[].pushedRequests.paging |
object | ||
sections[].pushedRequests.paging.firstRow |
integer | ||
sections[].pushedRequests.paging.lastRow |
integer | ||
sections[].pushedRequests.paging.page |
integer | ||
sections[].pushedRequests.paging.pages |
integer | ||
sections[].pushedRequests.paging.perPage |
integer | ||
sections[].pushedRequests.paging.total |
integer | ||
sections[].pushedRequests.total |
integer | ||
sections[].title |
string | ||
sections[].totals |
map | Each counter this section shows. | |
sections[].totals.{key} |
integer | ||
since |
string | ||
title |
string |
400: The answer.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/oauth2/monitor/delete-pushed-request
deletePushedRequest
Withdraw a pushed authorization request (RFC 9126)
Removes one pushed request, named by the SHA-256 of its request_uri, from this realm’s store of pushed authorization requests, live or spent. The authorization endpoint refuses it from then on with 400 invalid_request_uri, exactly as it refuses one that expired and was swept; a browser already on the sign-in or consent screen with it is refused when it comes back. Counted as par.deleted and written to the audit log. A value that is not a handle (43 characters of base64url), or one this realm does not hold, is refused 400. The store keeps no request_uri (#614), so the handle is the only name it answers to.
Mirrors POST /admin/oauth2/monitor 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 |
|---|---|---|---|
request_uri_digest |
string | yes | The request’s handle: the base64url SHA-256 of its whole request_uri, as listed by GET /admin-api/oauth2/monitor. |
200: The handle withdrawn, the client it was bound to and the state it was in.
| Member | Type | Required | What it is |
|---|---|---|---|
client_id |
list, or string, or number, or boolean, or null | ||
client_id[] |
string, or number, or boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
request_uri_digest |
string | ||
state |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
client_id |
list, or string, or number, or boolean, or null | ||
client_id[] |
string, or number, or boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
request_uri_digest |
string | ||
state |
string |