The Grant Negotiation and Authorization Protocol (RFC 9635) and its resource server connections (RFC 9767): the authorization server of this realm, what the applications using it have done, and the two things an operator does to its state by hand.
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/gnap
getGnap
The GNAP authorization server: endpoints, capabilities, grants, resource sets, settings
Everything /admin/gnap draws. The endpoints of this realm’s GNAP authorization server (RFC 9635) and its RS-facing API (RFC 9767); the section 9 capabilities of the default authorization server and of each named one (paged, serversPage, answered by authorizationServersPaging), after that profile’s GNAP overrides — which are what each grant endpoint ENFORCES; the five token formats and the public material that verifies the self-contained ones; the grants this realm holds (paged, grantsPage, and filtered by state); the registered resource sets (paged, resourcesPage); and the gnap.* settings, which are written through POST /admin-api/config/set-many.
Mirrors GET /admin/gnap on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
state |
query | string | A grant state, narrowing the grants; any other value is no filter at all. | |
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. | |
grantsPage |
query | integer | Which page of grants to return, answered by grantsPaging. The grants, newest first. |
|
resourcesPage |
query | integer | Which page of resources to return, answered by resourcesPaging. The registered resource sets. |
|
serversPage |
query | integer | Which page of servers to return, answered by serversPaging. The named authorization servers. |
|
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 authorization server as the page draws it.
| Member | Type | Required | What it is |
|---|---|---|---|
actions |
list | ||
actions[] |
string | ||
authorizationServers |
list | ||
authorizationServers[].capabilities |
object | ||
authorizationServers[].capabilities.assertion_formats_supported |
list, or string, or boolean, or null | ||
authorizationServers[].capabilities.assertion_formats_supported[] |
string | ||
authorizationServers[].capabilities.grant_request_endpoint |
string | ||
authorizationServers[].capabilities.interaction_finish_methods_supported |
list, or string, or boolean, or null | ||
authorizationServers[].capabilities.interaction_finish_methods_supported[] |
string | ||
authorizationServers[].capabilities.interaction_start_modes_supported |
list, or string, or boolean, or null | ||
authorizationServers[].capabilities.interaction_start_modes_supported[] |
string | ||
authorizationServers[].capabilities.key_proofs_supported |
list, or string, or boolean, or null | ||
authorizationServers[].capabilities.key_proofs_supported[] |
string | ||
authorizationServers[].capabilities.key_rotation_supported |
list, or string, or boolean, or null | ||
authorizationServers[].capabilities.key_rotation_supported[] |
string | ||
authorizationServers[].capabilities.sub_id_formats_supported |
list, or string, or boolean, or null | ||
authorizationServers[].capabilities.sub_id_formats_supported[] |
string | ||
authorizationServers[].capabilities.token_formats_supported |
list, or string, or boolean, or null | ||
authorizationServers[].capabilities.token_formats_supported[] |
string | ||
authorizationServers[].id |
string | ||
authorizationServers[].label |
string | ||
authorizationServersPaging |
object | ||
authorizationServersPaging.firstRow |
integer | ||
authorizationServersPaging.lastRow |
integer | ||
authorizationServersPaging.noun |
string | ||
authorizationServersPaging.page |
integer | ||
authorizationServersPaging.pages |
integer | ||
authorizationServersPaging.param |
string | ||
authorizationServersPaging.perPage |
integer | ||
authorizationServersPaging.total |
integer | ||
capabilities |
object | ||
capabilities.assertion_formats_supported |
list, or string, or boolean, or null | ||
capabilities.assertion_formats_supported[] |
string | ||
capabilities.grant_request_endpoint |
string | ||
capabilities.interaction_finish_methods_supported |
list, or string, or boolean, or null | ||
capabilities.interaction_finish_methods_supported[] |
string | ||
capabilities.interaction_start_modes_supported |
list, or string, or boolean, or null | ||
capabilities.interaction_start_modes_supported[] |
string | ||
capabilities.key_proofs_supported |
list, or string, or boolean, or null | ||
capabilities.key_proofs_supported[] |
string | ||
capabilities.key_rotation_supported |
list, or string, or boolean, or null | ||
capabilities.key_rotation_supported[] |
string | ||
capabilities.sub_id_formats_supported |
list, or string, or boolean, or null | ||
capabilities.sub_id_formats_supported[] |
string | ||
capabilities.token_formats_supported |
list, or string, or boolean, or null | ||
capabilities.token_formats_supported[] |
string | ||
enabled |
boolean | ||
endpoints |
object | ||
endpoints.accessTokenStatusList |
string | ||
endpoints.biscuitRevocations |
string | ||
endpoints.continuation |
string | ||
endpoints.discovery |
string | ||
endpoints.grant |
string | ||
endpoints.introspection |
string | ||
endpoints.keys |
string | ||
endpoints.resourceRegistration |
string | ||
endpoints.rsDiscovery |
string | ||
endpoints.tokenManagement |
string | ||
endpoints.userCode |
string | ||
endpoints.zcapController |
string | ||
grants |
object | ||
grants.paging |
object | ||
grants.paging.firstRow |
integer | ||
grants.paging.lastRow |
integer | ||
grants.paging.noun |
string | ||
grants.paging.page |
integer | ||
grants.paging.pages |
integer | ||
grants.paging.param |
string | ||
grants.paging.perPage |
integer | ||
grants.paging.total |
integer | ||
grants.rows |
list | ||
grants.rows[].authorizationServer |
string, or null | ||
grants.rows[].client |
string, or null | ||
grants.rows[].createdAt |
string, or number, or null | ||
grants.rows[].decision |
string, or null | ||
grants.rows[].derivedFrom |
string, or null | ||
grants.rows[].finalization |
object | ||
grants.rows[].finalization.at |
string, or number, or null | ||
grants.rows[].finalization.note |
string, or null | ||
grants.rows[].finalization.reason |
string | ||
grants.rows[].grantEndpoint |
string, or null | ||
grants.rows[].grantExpiresAt |
string, or number, or null | ||
grants.rows[].history |
list | ||
grants.rows[].history[].at |
string, or number, or null | ||
grants.rows[].history[].note |
string, or null | ||
grants.rows[].history[].state |
string | ||
grants.rows[].id |
string | ||
grants.rows[].interaction |
object | ||
grants.rows[].interaction.expiresAt |
string, or number, or null | ||
grants.rows[].interaction.finish |
string, or null | ||
grants.rows[].interaction.modes |
list | ||
grants.rows[].interaction.modes[] |
string | ||
grants.rows[].interaction.started |
string, or number, or null | ||
grants.rows[].proof |
string, or null | ||
grants.rows[].resourceOwner |
string, or null | ||
grants.rows[].state |
string | ||
grants.rows[].tokens |
integer | ||
grants.rows[].updatedAt |
string, or number, or null | ||
grants.state |
string, or null | ||
grants.states |
list | ||
grants.states[] |
string | ||
page |
string | ||
resourceSets |
object | ||
resourceSets.paging |
object | ||
resourceSets.paging.firstRow |
integer | ||
resourceSets.paging.lastRow |
integer | ||
resourceSets.paging.noun |
string | ||
resourceSets.paging.page |
integer | ||
resourceSets.paging.pages |
integer | ||
resourceSets.paging.param |
string | ||
resourceSets.paging.perPage |
integer | ||
resourceSets.paging.total |
integer | ||
resourceSets.rows |
list | ||
resourceSets.rows[].access |
list | ||
resourceSets.rows[].access[] |
any JSON | An RFC 9635 section 8 access right as a resource server registered it: a string reference, or an object whose members are that API’s own. An RFC 9635 section 8 access right as a resource server registered it: a string reference, or an object whose members are that API’s own. | |
resourceSets.rows[].createdAt |
string, or number, or null | ||
resourceSets.rows[].introspectionRequired |
boolean | ||
resourceSets.rows[].reference |
string | ||
resourceSets.rows[].resourceServer |
string | ||
resourceSets.rows[].tokenFormats |
list | ||
resourceSets.rows[].tokenFormats[] |
string | ||
settings |
object | ||
settings.context |
object | ||
settings.context.configFile |
string, or null | ||
settings.context.defaultsFile |
string, or null | ||
settings.context.inRealm |
boolean | ||
settings.context.persistenceMode |
string | ||
settings.context.persistsAppconfig |
boolean | ||
settings.context.persistsRealms |
boolean | ||
settings.context.realmId |
string | ||
settings.editableCount |
integer | ||
settings.groups |
list | ||
settings.groups[].group |
string | ||
settings.groups[].settings |
list | ||
settings.groups[].settings[].appconfigPath |
string | ||
settings.groups[].settings[].csvValueNotes |
map | ||
settings.groups[].settings[].csvValueNotes.{key} |
string | ||
settings.groups[].settings[].csvValues |
list | ||
settings.groups[].settings[].csvValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].default |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].default[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].description |
string | ||
settings.groups[].settings[].editRefusal |
string | ||
settings.groups[].settings[].editable |
boolean | ||
settings.groups[].settings[].enumValues |
list | ||
settings.groups[].settings[].enumValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].env |
list, or string | ||
settings.groups[].settings[].env[] |
string | ||
settings.groups[].settings[].group |
string | ||
settings.groups[].settings[].key |
string | ||
settings.groups[].settings[].label |
string | ||
settings.groups[].settings[].legacyEnv |
list, or string | ||
settings.groups[].settings[].legacyEnv[] |
string | ||
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, or null | ||
settings.groups[].settings[].type |
string | ||
settings.groups[].settings[].value |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].value[] |
string, or number, or boolean, or null | ||
settings.overridden |
list | ||
settings.overridden[] |
string | ||
settings.page |
string | ||
settings.setWith |
string | ||
settings.settingCount |
integer | ||
settings.sharedWith |
map | ||
settings.sharedWith.{key} |
list | ||
settings.sharedWith.{key}[].label |
string | ||
settings.sharedWith.{key}[].path |
string | ||
specifications |
list | ||
specifications[] |
string | ||
title |
string | ||
tokenFormats |
list | ||
tokenFormats[] |
string | ||
verificationMaterial |
object | ||
verificationMaterial.biscuit |
object | ||
verificationMaterial.biscuit.algorithm |
string | ||
verificationMaterial.biscuit.jwk |
object | ||
verificationMaterial.biscuit.jwk.alg |
string | ||
verificationMaterial.biscuit.jwk.crv |
string | ||
verificationMaterial.biscuit.jwk.e |
string | ||
verificationMaterial.biscuit.jwk.ek |
string | ||
verificationMaterial.biscuit.jwk.ext |
boolean | ||
verificationMaterial.biscuit.jwk.key_ops |
list | ||
verificationMaterial.biscuit.jwk.key_ops[] |
string | ||
verificationMaterial.biscuit.jwk.kid |
string | ||
verificationMaterial.biscuit.jwk.kty |
string | ||
verificationMaterial.biscuit.jwk.n |
string | ||
verificationMaterial.biscuit.jwk.pub |
string | ||
verificationMaterial.biscuit.jwk.use |
string | ||
verificationMaterial.biscuit.jwk.x |
string | ||
verificationMaterial.biscuit.jwk.x5c |
list | ||
verificationMaterial.biscuit.jwk.x5c[] |
string | ||
verificationMaterial.biscuit.jwk.x5t |
string | ||
verificationMaterial.biscuit.jwk.x5t#S256 |
string | ||
verificationMaterial.biscuit.jwk.x5u |
string | ||
verificationMaterial.biscuit.jwk.y |
string | ||
verificationMaterial.biscuit.revocation_endpoint |
string | ||
verificationMaterial.biscuit.root_public_key |
string | ||
verificationMaterial.biscuit.root_public_keys |
list | ||
verificationMaterial.biscuit.root_public_keys[] |
string | ||
verificationMaterial.jwt |
object | ||
verificationMaterial.jwt.alg |
string | ||
verificationMaterial.jwt.jwks_uri |
string | ||
verificationMaterial.jwt.kid |
string | ||
verificationMaterial.jwt.status_list_aggregation_endpoint |
string | ||
verificationMaterial.jwt.typ |
string | ||
verificationMaterial.jwt-encrypted |
object | ||
verificationMaterial.jwt-encrypted.authorization_server |
string | ||
verificationMaterial.jwt-encrypted.resource_server |
string | ||
verificationMaterial.macaroon |
object | ||
verificationMaterial.macaroon.root_key |
string | ||
verificationMaterial.zcap |
object | ||
verificationMaterial.zcap.controller |
string | ||
verificationMaterial.zcap.cryptosuite |
string |
POST /admin-api/gnap/delete-resource-set
deleteGnapResourceSet
Delete a registered resource set (RFC 9767 section 3.4)
Removes the resource set, after which its reference no longer resolves in a grant request. Tokens already issued keep the rights they carry.
Mirrors POST /admin/gnap 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 |
|---|---|---|---|
reference |
string | yes | The resource reference, from GET /admin-api/gnap. |
200: The reference that was deleted.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
reference |
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 | |
reference |
string |
GET /admin-api/gnap/monitor
getGnapMonitor
Every application that uses GNAP, and what each has done
Everything /admin/gnap/monitor draws: one row per application declared for GNAP, seen speaking it, or counted — client instances and resource servers — with the grants it holds by state, its live tokens, and its counters since the process started: grants requested, approved and denied, tokens issued by format, rotations, revocations, failed key proofs, introspections, registrations, derivations, and the GNAP error codes it was answered with. Per trust realm, and with no reset: the durable record is GET /admin-api/audit.
Mirrors GET /admin/gnap/monitor 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 totals, and one row per application.
| Member | Type | Required | What it is |
|---|---|---|---|
applications |
integer | ||
events |
list | ||
events[].counter |
string | ||
events[].event |
string | ||
events[].label |
string | ||
page |
string | ||
paging |
object | ||
paging.firstRow |
integer | ||
paging.lastRow |
integer | ||
paging.noun |
string | ||
paging.page |
integer | ||
paging.pages |
integer | ||
paging.param |
string | ||
paging.perPage |
integer | ||
paging.total |
integer | ||
rows |
list | ||
rows[].activeTokens |
integer | ||
rows[].counters |
map | ||
rows[].counters.{key} |
map, or number, or string, or null | ||
rows[].counters.{key}.{key} |
number | ||
rows[].finishUris |
list | ||
rows[].finishUris[] |
string | ||
rows[].grantsHeld |
object | ||
rows[].grantsHeld.approved |
integer | ||
rows[].grantsHeld.finalized |
integer | ||
rows[].grantsHeld.pending |
integer | ||
rows[].grantsHeld.total |
integer | ||
rows[].identifier |
string | ||
rows[].kinds |
list | ||
rows[].kinds[] |
string | ||
rows[].lastAt |
string, or number, or null | ||
rows[].lastEvent |
string, or null | ||
rows[].name |
string, or null | ||
rows[].registered |
boolean | ||
rows[].role |
string | ||
rows[].webApplication |
boolean | ||
since |
string, or number, or null | ||
title |
string | ||
tokensByFormat |
map | ||
tokensByFormat.{key} |
number | ||
totals |
map | ||
totals.{key} |
number |
POST /admin-api/gnap/revoke-grant
revokeGnapGrant
Revoke a GNAP grant, as its client could (RFC 9635 section 5.4)
Finalizes the grant and revokes every access token issued under it, through the same path the client’s own DELETE on the continuation URI takes — so the client sees exactly what it would have seen had it revoked the grant itself, and a CAEP session-revoked is sent to every stream that takes it. A grant already finalized is reported unchanged rather than refused — except one finalized as issued, whose tokens are still live and are revoked (#432). Naming user as well revokes it only if that person is its resource owner — the per-person door the GNAP grants tab of /admin/users uses, whose grants GET /admin-api/users?user= lists as gnapGrants.
Mirrors POST /admin/gnap 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 |
|---|---|---|---|
grant |
string | yes | The grant identifier, from GET /admin-api/gnap or the person’s gnapGrants. |
user |
string | The person whose grant it must be (optional). A grant whose resource owner is somebody else is refused and nothing changes. |
200: The grant as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
grant |
object | ||
grant.authorizationServer |
string, or null | ||
grant.client |
string, or null | ||
grant.createdAt |
string, or number, or null | ||
grant.decision |
string, or null | ||
grant.derivedFrom |
string, or null | ||
grant.finalization |
object | ||
grant.finalization.at |
string, or number, or null | ||
grant.finalization.note |
string, or null | ||
grant.finalization.reason |
string | ||
grant.grantEndpoint |
string, or null | ||
grant.grantExpiresAt |
string, or number, or null | ||
grant.history |
list | ||
grant.history[].at |
string, or number, or null | ||
grant.history[].note |
string, or null | ||
grant.history[].state |
string | ||
grant.id |
string | ||
grant.interaction |
object | ||
grant.interaction.expiresAt |
string, or number, or null | ||
grant.interaction.finish |
string, or null | ||
grant.interaction.modes |
list | ||
grant.interaction.modes[] |
string | ||
grant.interaction.started |
string, or number, or null | ||
grant.proof |
string, or null | ||
grant.resourceOwner |
string, or null | ||
grant.state |
string | ||
grant.tokens |
integer | ||
grant.updatedAt |
string, or number, or null | ||
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 | ||
grant |
object | ||
grant.authorizationServer |
string, or null | ||
grant.client |
string, or null | ||
grant.createdAt |
string, or number, or null | ||
grant.decision |
string, or null | ||
grant.derivedFrom |
string, or null | ||
grant.finalization |
object | ||
grant.finalization.at |
string, or number, or null | ||
grant.finalization.note |
string, or null | ||
grant.finalization.reason |
string | ||
grant.grantEndpoint |
string, or null | ||
grant.grantExpiresAt |
string, or number, or null | ||
grant.history |
list | ||
grant.history[].at |
string, or number, or null | ||
grant.history[].note |
string, or null | ||
grant.history[].state |
string | ||
grant.id |
string | ||
grant.interaction |
object | ||
grant.interaction.expiresAt |
string, or number, or null | ||
grant.interaction.finish |
string, or null | ||
grant.interaction.modes |
list | ||
grant.interaction.modes[] |
string | ||
grant.interaction.started |
string, or number, or null | ||
grant.proof |
string, or null | ||
grant.resourceOwner |
string, or null | ||
grant.state |
string | ||
grant.tokens |
integer | ||
grant.updatedAt |
string, or number, or null | ||
message |
string | ||
ok |
boolean | yes |