Every console control, reachable by a machine. How to get a token and call it.

The management API of IYA STS: everything the /admin console shows and everything it can change, over JSON, with no browser.

Every operation here requires an OAuth 2.0 access token, and this document says which scope each one needs. Ask this service’s own token endpoint for one: grant_type=client_credentials as the seeded client sts-api-client (its secret is adminApi.clientSecret), scope=admin:read admin:write, and resource=<this server>/admin-api — that last parameter is what puts this API in the token’s aud, and a token audienced at anything else is refused however good it is. A GET needs admin:read and everything else needs admin:write; they are checked as a XACML access decision against the built-in ADMIN_READ and ADMIN_WRITE roles, so the requirement is stated in the same policy document as every other access decision in this service. The credential is service-wide: the token is verified against the DEFAULT realm’s key and audienced without a realm prefix wherever it is presented, for the reason the console’s two roles are groups in the default realm — a per-realm one would let anybody who can create a realm mint themselves an administrator. A trust realm’s own administrators have a narrower token of their own: issued to that realm’s sts-api-client client, accepted only under /realm/<id>/admin-api, and refused every service-wide operation. adminApi.authRequired turns this off and restores the open API exactly; what follows is what that means. AND IT IS STILL WORTH STATING PLAINLY: a holder of this token can revoke every token this service has issued and change what the next one contains. That is fine on a laptop or a compose network and is not fine on a public address, which was already true of /oauth2/token — it will mint a token for any username asked of it.

Many operations change what the protocol endpoints do, rather than only reporting on them; four examples. Revoking a token is the same revocation RFC 7009’s /oauth2/revoke performs, so introspection, UserInfo and the refresh grant all honour it immediately. A custom claim reaches every access token, ID Token and SAML assertion issued from then on. The credential claim set reaches every Verifiable Credential AND sweeps the embedded LDAP directory. And the verifier request reaches the dcql_query of the next OID4VP Authorization Request. Nothing already issued ever changes — a signed document cannot be reached into.

Every operation here mirrors a control on the /admin console and calls the same function behind it. They are not two implementations of one idea: admin_api.js holds no opinion about what a revocation means that the console does not. The mirrors line on each operation says which control it is.

In the default memory persistence mode all state is in memory and dies with the process; GET /admin-api/persistence says what this process writes down.

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.

Sections

Section Operations What it covers
ACME 8  
Admin roles 3  
Applications 50  
Audit log 3 What happened here, in order — history rather than state, and read-only. It carries no credential of any kind and has no clear operation: an erase control on an administrative surface would make an audit log unable to answer the one question it exists for.
Authorization servers 6  
CAEP 5  
Cluster 1  
Configuration 10  
Credential claims 6 What an issued Verifiable Credential carries.
Credential status 5 The status lists every issued Verifiable Credential names, and suspending, reinstating or revoking one: Monitoring → Verifiable Credentials (/admin/vc/monitor) in the console.
Custom SAML attributes 9 What to add to every SAML 2.0 and SAML 1.1 assertion issued from now on — WS-Trust’s and WS-Federation’s alike. The same store the custom claims are in, and the same two halves: a typed attribute and a directory one.
Custom claims 9 What to add to every access token and ID Token issued from now on. The assertions are next door, under Custom SAML attributes.
Delegation 17  
Devices 11  
Directory 17  
EST 6  
Federation 24  
GNAP 4 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.
Groups 7 The embedded LDAP directory’s groups. A group here GRANTS NOTHING: no token, assertion, ticket or PAC carries one and no endpoint reads one.
Kerberos 28  
LDAP 10  
Metrics 1 What this service has done since it started.
Monitoring 13  
Multi-factor authentication 4  
OAuth 2.0 / OIDC 14  
OpenID Federation 19  
OpenID4VCI 3  
OpenID4VP 1  
Ownership 2  
PKI 26  
Persistence 1  
Policies 26 The rules this realm holds a credential to — the password policy first: its minimum length, how many previous passwords may not be reused, and the symbol, uppercase and digit rules, stored as cn=default,ou=passwordPolicies in the directory and ENFORCED IN PRODUCT MODE at every door that sets a password. Not the XACML policy repository, which is under XACML.
RISC 5  
Recovery codes 1  
Risk 10  
Roles 13 Who holds a role, and what requires one. A role is a name a person, a GROUP or an APPLICATION can be mapped into, and holding one is what an ISSUANCE is decided on — which is the whole difference from Groups above, where a group grants nothing. The decision is made by the XACML PDP against a policy, never by an if in an issuance site, so a refusal is a document somebody can read. It is not Admin roles either: those are two directory groups that grant the /admin console and nothing else.
SAML 1.1 2  
SAML 2.0 13  
SAML assertions 3  
SCEP 8 The Simple Certificate Enrolment Protocol (RFC 8894) server of this realm: its Issuing CA and RA certificate, the single-use challenge passwords that authorize an enrollment, registered host names, the certificates issued over it, and what it has done.
SCIM 13 The SCIM 2.0 provisioning endpoints under /scim/v2 — what they have been asked to do, and what they will and will not do. READ-ONLY here, and that is the parity rule holding rather than a gap: the console page has no form on it either, because everything about SCIM that can be changed is a configuration row. What SCIM WROTE is under Users and Groups, since it provisions into the same directory and has no store of its own.
SPIFFE 16  
Service 44 What this API is, its document, and the explorer that calls it.
Sessions 3  
Shared Signals 14  
Sign-out 6  
TLS 5  
TOTP MFA 1  
Token lifetimes 3 How long an access token, an ID Token and a refresh token issued here last, and how far out a clock may be before this service stops believing one of its own. Four of the settings under Configuration, behind a name that promises four rather than forty-nine — and a door that refuses a key it does not recognise instead of ignoring it.
Tokens 14 What has been issued, and the revocation of the three kinds that can be revoked.
Trust realms 6  
UMA 11  
UserInfo claims 9  
Users 67 Who it has authenticated, and what each of them holds.
Verifier request 8 What this realm’s OID4VP Verifier asks a wallet for.
WS-Federation 1  
WS-Trust 1  
WebAuthn 1  
XACML 90