users_sessions_get

Tool

users_sessions_get

Read one end-user session in full: its status, device metadata, both expiries, the assurance level and factors it was established with, why it was revoked if it was, and the operator behind it if it is an impersonated session.

Behavior

HTTP: GET /users/sessions/:sessionId

Arguments

Name	Type	Required	Description
sessionId	string	•	The session to read.

Response

Field	Type	Always	Description
id	string	•	Id of this session. Pass it to users_sessions_revoke.
ip	string	•	IP the session was opened from. Null when it was not recorded.
aal	string	•	`aal2` only if a verified second factor completed.
amr	array	•	The factors this session was established with.
status	string	•	Whether the session is still usable, expired, or revoked.
userId	string	•	The end user this session belongs to.
createdAt	string	•	When the session was opened (ISO 8601).
expiresAt	string	•	When the current token stops working unless refreshed (ISO 8601).
revokedAt	string	•	When the session was revoked (ISO 8601). Null while it is live.
userAgent	string	•	User agent the session was opened from. Null when none was sent.
revokedReason	string	•	Why the session ended, when it was revoked — e.g. `signout`, `ban`, `mfa_reset`. Null while it is live. The vocabulary is additive, so it is not an enum.
impersonatedBy	string	•	The operator behind an impersonated session, or null for an ordinary one.
lastRefreshedAt	string	•	When the session last refreshed its tokens (ISO 8601). Null if it never has.
absoluteExpiresAt	string	•	When the session ends no matter how often it refreshes (ISO 8601).

Try it

Read one end-user session in full: its status, device metadata, both expiries, the assurance level and factors it was established with, why it was revoked if it was, and the operator behind it if it is an impersonated session.

When to use

Example

Ask your agent something like this:

Read one end-user session in full: its status, device metadata, both expiries, the assurance level and factors it was established with, why it was revoked if it was, and the operator behind it if it is an impersonated session.

The agent will invoke users_sessions_get with these arguments:

{
  "sessionId": "<sessionId>"
}