List an organization's active sessions (admin)
/v1/admin/orgs/{slug}/sessionsReturns one page of the sign-in sessions that are active in slug's
organization, using opaque cursor (keyset) pagination. Bound the page
size with limit and choose an ordering with sort (see
x-sort-fields for what this endpoint accepts; the session id is
appended so the ordering is total). Then walk the listing by passing the
previous response's page.next_cursor back as cursor for as long as
page.has_more is true; page.prev_cursor steps back the same way.
Defaults to newest sign-in first.
Which sessions are active. A session is listed while it would still sign its user in: before its absolute expiry, and no longer idle than the idle timeout allows — the same rule the server applies when the session is presented. A session that has already died is never listed, whether or not it has been swept yet. Sessions that have ended are not part of this listing.
user_id narrows the listing to one user's sessions and client_id to
the sessions a client took part in; they compose as a conjunction. A
cursor is bound to the filters it was issued for, so send them with it;
the order it carries itself.
Each session carries its public id — the sid its relying parties
receive — and never the credential its browser holds or anything derived
from it. The user's display name, and the address and user agent the
session was established from, are personal data: a caller without the
users.pii.read permission receives none of them, and each session names
what it withheld in withheld.
Reading the listing is audited. Requires the nauthera.sessions:read
scope and the sessions.read permission; the listing is confined to
slug's organization.
The organization slug. It names the TENANT OF RECORD for the operation: the rows it reads and writes, the policy its secrets are derived under, and the organization its audit record is filed against all come from this organization. A token is admitted only through its own slug, except a main-org token, which may be admitted through any — so cross-tenant administration is performed through the TARGET tenant's slug, never by naming its resources through another. A token reaching for a slug it may not be admitted through is refused identically whether that organization exists or not.
1–64 characters
- limitinteger
Maximum number of items to return in one page (1–200; default 50). A value outside that range is rejected with a 400. It may be changed freely between pages of the same walk — a cursor marks a position, not a page number.
Default50between 1 and 200
- sortstring
Ordering for the listing: a comma-separated list of fields, most significant first, a leading
-marking a descending term. For examplesort=last_name,-first_namesorts by last name ascending, then by first name descending.Show moreShow less
Which fields a given endpoint accepts is listed in its
x-sort-fieldsextension; naming anything else is a 400. A field may appear only once.The server always appends the resource's primary key as a final term, so the ordering is TOTAL — rows that tie on every field you named still have a defined relative order, without which a page could skip or repeat them. The full ordering, including that appended term, is echoed as
page.sort.Send it on the FIRST request of a walk only: every cursor records the ordering it was issued under, so it carries forward automatically, and a
sortthat contradicts the suppliedcursoris rejected with a 400 rather than silently reordering mid-walk.Sortable fields:
created_at,id. Prefix a field with-to sort descending.at most 256 characters · pattern
^-?[a-z][a-z0-9_]*(,-?[a-z][a-z0-9_]*)*$ - cursorstring
Opaque keyset cursor identifying where a page begins. Omit it for the first page; afterwards pass the
next_cursor(orprev_cursor) value from the previous response verbatim — the token itself records which direction it steps in, so there is no separate direction parameter.Show moreShow less
The token is server-defined and MUST be treated as opaque: it is bound to the listing and sort order that issued it, and a cursor that is malformed, tampered with, or belongs to a different listing or order is rejected with a 400 rather than silently paging through the wrong set.
at most 1024 characters
- user_idstring
Only the sessions of the user with this id.
at most 256 characters
- client_idstring
Only the sessions the client with this OAuth client id took part in.
at most 256 characters
- DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's
cnf.jktand cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.
200 OKapplication/jsonOne page of the organization's active sessions.
One page of the organization's active sessions.
Headers
Cache-Controlno-store
Body
One page of an organization's active sessions under cursor (keyset) pagination:
itemsholds the page, ordered by the request'ssort, andpagesays where it sits in the listing. Followpage.next_cursorwhilepage.has_moreis true.The sessions on this page.
Each item:An active sign-in session as the admin API lists it: whose it is, when it began and was last used, how its user authenticated, the clients that took part in it, and when it ends.
Show moreShow less
idis the session's PUBLIC identifier — thesidits relying parties receive in ID and logout tokens, and thesession_idits audit records carry. The credential the browser holds, and anything derived from it, is never returned.Show item attributesHide item attributes
The public session id: the
sidclaim of every ID token issued in this session.The id of the user the session belongs to.
The user's username within the organization.
When the user signed in and the session began.
When the user last authenticated in this session (OIDC
auth_time).When the session was last used. Refreshed lazily, so it may trail the most recent use by up to a minute.
When the session ends if it is not used again:
last_seen_atplus the idle timeout. The session ends at whichever of this andexpires_atcomes first.When the session ends however it is used: its absolute lifetime, fixed when it began.
The authentication methods the user satisfied (OIDC
amr, RFC 8176), such aspwd,otpandmfa.The OAuth client ids of the clients that took part in the session — each was issued an authorization code in it — sorted. Empty when none has yet.
The personal fields left out of this session because the caller lacks the
users.pii.readpermission, in a fixed order; empty when nothing was withheld. A field named here is absent because it was withheld, not because it is unknown.Each item:A personal field of a session that was left out because the caller lacks the
users.pii.readpermission: the user's display name, the address the session was established from, or its user agent.Possible values"display_name""ip""user_agent"- display_namestring
The user's display name. Absent when they have none, or when it was withheld (see
withheld). - acrstring
The authentication context class satisfied (OIDC
acr). Absent when none was recorded. - ipstring
The address the session was established from. Absent when it was not recorded, or when it was withheld (see
withheld). - user_agentstring
The user agent the session was established from. Absent when it was not recorded, or when it was withheld (see
withheld).
Where one page sits in a cursor (keyset) paginated list, returned beside that page's
items.Show moreShow less
Walk a list by following
next_cursorfor as long ashas_moreis true, passing the token back verbatim as thecursorquery parameter. Keep the listing and its filters the same for the whole walk;limitMAY change between pages (a cursor marks a position, not a page number), andsorttravels in the cursor so it need not be resent.has_moreis authoritative: it is derived from whether a further row actually exists, so a page that happens to be full is not mistaken for a page that has a successor, and a walk never costs a trailing empty request.prev_cursorsteps back the same way.A cursor is opaque — server-defined, bound to this listing and sort order, and not parseable by clients. It stays valid across page-size changes but not across a change of sort order or filters; a cursor that does not belong to the request is rejected with a 400 rather than silently paging through the wrong set.
Keyset paging is stable under concurrent writes, with one qualification. A row whose SORT KEY does not change is returned exactly once for the whole walk. Rows created or deleted mid-walk may or may not appear, depending on which side of the cursor they fall — and so may a row whose sort key is UPDATED mid-walk, since that moves it across the boundary: it can be seen twice or missed. Sorting by a field that does not change (the default id ordering, or
created_at) avoids this entirely.Show child attributesHide child attributes
The page size in effect: the
limitthat was sent, or the server's default when it was omitted. Echoed so a client resuming from a stored cursor knows the page size without having to remember it.Example50The ordering this walk is pinned to, in the
sortparameter's syntax and INCLUDING the primary-key term the server appends to make it total. Cursors carry it, so it need only be sent on the first request.Example"last_name,-first_name,id"Whether a page follows this one and
next_cursorcan reach it. When false this is the last page andnext_cursoris absent.Whether a page precedes this one and
prev_cursorcan reach it. False on the first page of a walk.Show moreShow less
Both flags report REACHABILITY, not bare existence. A cursor that overshoots the set — a stale bookmark, or rows deleted mid-walk — returns an empty page with both flags false even though rows precede it, because an empty page has no row to anchor a cursor on. Restart the walk if you land there; a client following
has_morenever does.- next_cursorstring
Opaque cursor for the next page. Present exactly when
has_moreis true, and ABSENT (the field is omitted, not null) otherwise. Pass it back verbatim as thecursorquery parameter; never parse it.at most 512 characters
- prev_cursorstring
Opaque cursor for the previous page. Present exactly when
has_previs true, and absent otherwise. Passed back ascursor, exactly likenext_cursor— the token itself records which way it steps.at most 512 characters
400 Bad Requestapplication/problem+jsonThe pagination parameters or a filter were invalid — a malformed or foreign cursor, a cursor contradicting
sort, asortnaming a field this endpoint does not accept or naming one twice, alimitoutside its declared range, or a filter longer than its declared length.The pagination parameters or a filter were invalid — a malformed or foreign cursor, a cursor contradicting
sort, asortnaming a field this endpoint does not accept or naming one twice, alimitoutside its declared range, or a filter longer than its declared length.Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
401 Unauthorizedapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
403 Forbiddenapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"