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

Management API

What an issued Verifiable Credential carries.

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/credential-claims

getCredentialClaims

Which claims an issued Verifiable Credential carries

The catalogue, what is selected from it, and a preview of what one person’s credential would carry if it were issued now.

The catalogue is of LDAP ATTRIBUTE TYPES and not of claim names, because this service has a directory and a claim whose value nothing else can see is half a demonstration: the value of a claim is the value on that person’s entry under ou=users.

Mirrors GET /admin/vc 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
user query string   Whose credential to preview. Defaults to a person the directory holds from startup, so the preview shows real values on a fresh process.
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 catalogue, the selection and the preview.

Member Type Required What it is
attributes list    
attributes[].claim string    
attributes[].example object    
attributes[].example.source string    
attributes[].example.value list, or string, or number, or boolean, or null    
attributes[].example.value[] string, or number, or boolean    
attributes[].label string    
attributes[].ldap string    
attributes[].ldpTerm string    
attributes[].schema string    
attributes[].selected boolean    
defaults list    
defaults[] string    
ldpOmitted list    
ldpOmitted[] string    
preview object    
preview.claims object    
preview.claims.claims map   The credential subject’s claims.
preview.claims.claims.{key} one of 2 shapes, or string, or number, or boolean, or null    
preview.claims.claims.{key} (shape 1) list    
preview.claims.claims.{key} (shape 1)[] string, or number, or boolean    
preview.claims.claims.{key} (shape 2) map   A claim’s members, as address has.
preview.claims.claims.{key} (shape 2).{key} list, or string, or number, or boolean, or null    
preview.claims.claims.{key} (shape 2).{key}[] string, or number, or boolean    
preview.claims.entryFound boolean    
preview.claims.report list    
preview.claims.report[].claim string    
preview.claims.report[].ldap string    
preview.claims.report[].ldpTerm string, or null    
preview.claims.report[].source string    
preview.claims.report[].value list, or string, or number, or boolean, or null    
preview.claims.report[].value[] string, or number, or boolean    
preview.user 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    
selected list    
selected[] string    

POST /admin-api/credential-claims/add

addCredentialClaim

Add one attribute to the credential claim set

Sweeps the directory afterwards, as select does. An attribute already selected is refused rather than treated as done.

Mirrors POST /admin/vc#vc-tab-claims on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
(the answer) any JSON    

200: What is selected now, and what the sweep did.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

POST /admin-api/credential-claims/defaults

resetCredentialClaims

Back to the default selection

The attributes this issuer carried before the page existed. Sweeps afterwards, as select does.

Mirrors POST /admin/vc#vc-tab-claims 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 (optional)

An empty object.

200: The default selection, and what the sweep did.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

POST /admin-api/credential-claims/populate

populateDirectory

Sweep the directory without changing the selection

For a directory that gained entries after the last change — or one that was not running when it happened. Running it twice does nothing the second time, because the sweep only fills what is absent.

Mirrors POST /admin/vc#vc-tab-claims 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 (optional)

An empty object.

200: What the sweep examined and changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

POST /admin-api/credential-claims/remove

removeCredentialClaim

Remove one attribute from the credential claim set

Future credentials stop carrying it. What was already written onto a directory entry stays there — nothing here deletes an attribute value, because an operator may have set it.

Mirrors POST /admin/vc#vc-tab-claims on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
(the answer) any JSON    

200: What is selected now.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

POST /admin-api/credential-claims/select

selectCredentialClaims

Set the whole credential claim set

Replaces the selection, and then SWEEPS THE DIRECTORY: every person under ou=users gains the selected attributes they are missing, invented from their username — deterministically, so one username is one invented person across restarts. An attribute already there is never overwritten, so an operator’s ldapmodify and the seeded people’s own names survive.

The sweep is the point rather than a side effect: without it, selecting title would change every future credential and change nothing an LDAP client could see, and the two halves of this service would stop describing the same people. The reply’s sweep says what it did, including when there was no directory to do it to.

The issuer METADATA is built from this same selection, so what is advertised cannot drift from what is minted.

Mirrors POST /admin/vc#vc-tab-claims 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
attributes list yes LDAP attribute type names, from the catalogue.
attributes[] string    

200: What is selected now, what changed, and what the sweep did.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
selected list    
selected[] string    
sweep object    
sweep.attributes list    
sweep.attributes[] string    
sweep.changed integer    
sweep.errors list    
sweep.errors[] string    
sweep.examined integer    
sweep.loaded boolean    
sweep.ok boolean    
sweep.skipped boolean, or string    
sweep.values integer