This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

Management API

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