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 |