Management API

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.

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/token-lifetimes

getTokenLifetimes

How long tokens issued here are good for

The three lifetimes — access token, ID Token, refresh token — the clock skew applied wherever this service reads one of its own tokens back, and the two RFC 9700 mode refresh-token rules: the idle timeout and revocation on sign-out.

All six are ordinary configuration settings and appear in GET /config too; settings here is the same row shape, carrying each one’s bounds, its source and its default. lifetimes beside it is just the three lifetimes and the skew, for a caller that wants the value rather than the provenance.

It also reports WHAT IS ALREADY OUT THERE, per kind, counted against the same clock the endpoints use — the skew is applied to that count, so a token this calls expired is one POST /oauth2/introspect will report inactive.

A LIFETIME IS STAMPED INTO A TOKEN WHEN IT IS SIGNED, so changing one reaches the next token and nothing already issued. To take an issued token out of circulation, revoke it under Tokens.

Mirrors GET /admin/token-lifetimes on the admin console.

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: The six settings, and what has been issued under them.

Member Type Required What it is
context object    
context.configFile string, or null    
context.defaultsFile string, or null    
context.inRealm boolean    
context.persistenceMode string    
context.persistsAppconfig boolean    
context.persistsRealms boolean    
context.realmId string    
lifetimes object    
lifetimes.accessTokenTtlS number    
lifetimes.clockSkewS number    
lifetimes.idTokenTtlS number    
lifetimes.refreshTokenTtlS number    
now number    
overridable list    
overridable[].attribute string    
overridable[].setting string    
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each of a list’s values.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or string, or number, or boolean, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll object    
settings[].selectAll.aloneWhileOn list    
settings[].selectAll.aloneWhileOn[].canBeOn boolean    
settings[].selectAll.aloneWhileOn[].on boolean    
settings[].selectAll.aloneWhileOn[].setting string    
settings[].selectAll.aloneWhileOn[].values list    
settings[].selectAll.aloneWhileOn[].values[] string    
settings[].selectAll.onlyWhileOn list    
settings[].selectAll.onlyWhileOn[].canBeOn boolean    
settings[].selectAll.onlyWhileOn[].on boolean    
settings[].selectAll.onlyWhileOn[].setting string    
settings[].selectAll.onlyWhileOn[].values list    
settings[].selectAll.onlyWhileOn[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string    
settings[].type string    
settings[].value list, or string, or number, or boolean, or null    
settings[].value[] string    
tokens object    
tokens.byKind list    
tokens.byKind[].bound integer    
tokens.byKind[].expired integer    
tokens.byKind[].issued integer    
tokens.byKind[].kind string    
tokens.byKind[].noExpiry integer    
tokens.byKind[].notYetValid integer    
tokens.byKind[].revoked integer    
tokens.byKind[].valid integer    
tokens.cap number    
tokens.forgotten integer    
tokens.held integer    
tokens.revoked integer    

POST /admin-api/token-lifetimes/defaults

resetTokenLifetimes

Put the six back

Clears the runtime override on THESE SIX ONLY, so each falls back to its environment variable, the appconfig file, or env/defaults.js — one hour, one hour and twenty-four hours for the lifetimes, twenty-four hours idle, revocation on sign-out on, and thirty seconds of skew.

It is deliberately not POST /config/reset-all, which would also drop an override somebody set on an unrelated page. A test that changed only the lifetimes should call this to put the service back; one that changed more should call that one.

A setting that was not overridden is skipped rather than refused, because this means “put these six back” rather than “undo this one change” — the per-key refusal is on POST /config/reset, where it is the right answer.

Mirrors POST /admin/token-lifetimes 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 keys that had an override cleared, in cleared.

Member Type Required What it is
cleared list    
cleared[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each of a list’s values.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or string, or number, or boolean, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll object    
settings[].selectAll.aloneWhileOn list    
settings[].selectAll.aloneWhileOn[].canBeOn boolean    
settings[].selectAll.aloneWhileOn[].on boolean    
settings[].selectAll.aloneWhileOn[].setting string    
settings[].selectAll.aloneWhileOn[].values list    
settings[].selectAll.aloneWhileOn[].values[] string    
settings[].selectAll.onlyWhileOn list    
settings[].selectAll.onlyWhileOn[].canBeOn boolean    
settings[].selectAll.onlyWhileOn[].on boolean    
settings[].selectAll.onlyWhileOn[].setting string    
settings[].selectAll.onlyWhileOn[].values list    
settings[].selectAll.onlyWhileOn[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string    
settings[].type string    
settings[].value list, or string, or number, or boolean, or null    
settings[].value[] string    

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

Member Type Required What it is
cleared list    
cleared[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each of a list’s values.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or string, or number, or boolean, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll object    
settings[].selectAll.aloneWhileOn list    
settings[].selectAll.aloneWhileOn[].canBeOn boolean    
settings[].selectAll.aloneWhileOn[].on boolean    
settings[].selectAll.aloneWhileOn[].setting string    
settings[].selectAll.aloneWhileOn[].values list    
settings[].selectAll.aloneWhileOn[].values[] string    
settings[].selectAll.onlyWhileOn list    
settings[].selectAll.onlyWhileOn[].canBeOn boolean    
settings[].selectAll.onlyWhileOn[].on boolean    
settings[].selectAll.onlyWhileOn[].setting string    
settings[].selectAll.onlyWhileOn[].values list    
settings[].selectAll.onlyWhileOn[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string    
settings[].type string    
settings[].value list, or string, or number, or boolean, or null    
settings[].value[] string    

POST /admin-api/token-lifetimes/set

setTokenLifetimes

Set one or more of the six

A RUNTIME OVERRIDE, like every other change made through this API: written down and re-applied at the next start when persistence.appconfig has a store under it (persistence.realms for a write made inside a realm), and gone on restart only with persistence.mode=memory; the reply’s message says which. Nothing writes to the appconfig file in either case.

Name any of the six; the console form posts them all at once and a caller may post one. ALL-OR-NOTHING: every value is checked before any is written, so a body with one bad field changes nothing and names it.

UNLIKE POST /config/set-many, a property that is not one of the six is REFUSED rather than ignored. That door is for a form posting a whole section, where an unknown field is ordinary; this one is for a caller that means to set a lifetime, where a misspelt key that succeeded and changed nothing is the worst possible answer.

Every lifetime must be a whole number of THIRTY-SECOND units, between 30 and 2592000 (thirty days). The skew is 0 to 300 in the same units. The idle timeout is whole seconds, 0 turning it off, and revocation on sign-out is a boolean. Those bounds are on each setting’s row in the GET, so a client can render them rather than repeat them.

The change applies to the NEXT token signed. Nothing already issued is affected: a lifetime is a claim inside a signed statement.

Mirrors POST /admin/token-lifetimes 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
oauth2.accessTokenTtlS integer   Access token lifetime (s)
oauth2.clockSkewS integer   Token clock skew (s)
oauth2.idTokenTtlS integer   ID Token lifetime (s)
oauth2.refreshIdleSeconds integer   Refresh token idle timeout (s)
oauth2.refreshTokenTtlS integer   Refresh token lifetime (s)
oauth2.revokeRefreshOnLogout boolean   Revoke refresh tokens on sign-out

200: What was applied, in applied, and what actually changed, in changed.

Member Type Required What it is
applied list    
applied[] string    
changed list    
changed[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each of a list’s values.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or string, or number, or boolean, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll object    
settings[].selectAll.aloneWhileOn list    
settings[].selectAll.aloneWhileOn[].canBeOn boolean    
settings[].selectAll.aloneWhileOn[].on boolean    
settings[].selectAll.aloneWhileOn[].setting string    
settings[].selectAll.aloneWhileOn[].values list    
settings[].selectAll.aloneWhileOn[].values[] string    
settings[].selectAll.onlyWhileOn list    
settings[].selectAll.onlyWhileOn[].canBeOn boolean    
settings[].selectAll.onlyWhileOn[].on boolean    
settings[].selectAll.onlyWhileOn[].setting string    
settings[].selectAll.onlyWhileOn[].values list    
settings[].selectAll.onlyWhileOn[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string    
settings[].type string    
settings[].value list, or string, or number, or boolean, or null    
settings[].value[] string    

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

Member Type Required What it is
applied list    
applied[] string    
changed list    
changed[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each of a list’s values.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or string, or number, or boolean, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll object    
settings[].selectAll.aloneWhileOn list    
settings[].selectAll.aloneWhileOn[].canBeOn boolean    
settings[].selectAll.aloneWhileOn[].on boolean    
settings[].selectAll.aloneWhileOn[].setting string    
settings[].selectAll.aloneWhileOn[].values list    
settings[].selectAll.aloneWhileOn[].values[] string    
settings[].selectAll.onlyWhileOn list    
settings[].selectAll.onlyWhileOn[].canBeOn boolean    
settings[].selectAll.onlyWhileOn[].on boolean    
settings[].selectAll.onlyWhileOn[].setting string    
settings[].selectAll.onlyWhileOn[].values list    
settings[].selectAll.onlyWhileOn[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string    
settings[].type string    
settings[].value list, or string, or number, or boolean, or null    
settings[].value[] string