List user sessions

Read sessions for the caller or a managed user.

Outcome

Read sessions for the caller or a managed user.

These examples prove local handler behavior with real isolated SQL and explicitly simulated identity/permission dependencies.

Before you start

Verify the intended authenticated identity and the current credential-scoped action before preparing input. Self and managed-user security operations have different authority; a session id does not authorize a different user.
Use authorized identity and user/session discovery. Recovery security data and session/device identifiers must remain inside the caller-approved workflow.

Discover the target

topolo whoami --json
topolo apps --json
topolo actions get app_topolo_auth.sessions.list --detail --json

For user/session actions use the caller subject or a user returned by authorized users discovery, then sessions.list for that exact user. For recovery read me.recovery_email.get before reviewing an approved address. Tenant identity takes no override input.

Input fields

Field	Required	Meaning
`userId`	Yes	Existing target Auth user id from authorized identity/user discovery. Self access accepts the subject or userId identity alias; managed-user access requires target-user authority. It does not authorize sessions of another user.
`status`	No	Use active, revoked or all. Default active excludes expired sessions; revoked includes all stored revoked rows; all includes expired rows. There is no pagination. Legacy unknown strings fall back to active; never use that behavior to request an undocumented status.

Effects

Reads sessions of self or an authorized managed user; default returns only active unexpired records.

Interpret the response

Success is HTTP 200 with raw target success/message/data/timestamp. CLI/MCP can wrap or project that response. Record timestamps are epoch seconds; the envelope timestamp is ISO text. These local fixtures simulate token identities, so no response proves live sign-in or browser OAuth recovery.

Session list uses snake_case stored columns, ordered by last_activity descending, with no limit or continuation. Default active excludes expired rows; revoked uses stored status; all includes expired records. Device JSON has variable shape and malformed/absent JSON becomes an empty object. The current store maps a SQL read error to an empty successful list, so an empty result alone cannot prove that no sessions exist.

Missing access tokens return AUTH_ERROR. A thrown invalid-token error currently becomes SERVER_ERROR in these handlers. Session/recovery/logout prefer an access cookie when present; tenant lookup prefers the Bearer header. Do not combine identities across cookie and Bearer transports or infer an OAuth expiry from every 401/500.

Worked examples

These are complete raw target-handler responses, not CLI/gateway envelopes or live authorization proof. Replace synthetic identifiers using authorized discovery. Save only the reviewed input as payload.json; inspect validation and plan before executing. --confirm assumes the intended operation is approved. Storage and response read-back require separate live token rejection, delivery and recipient verification proof where relevant. Cookies and Bearer tokens must identify the intended principal consistently.

Default list includes active unexpired sessions only

Input · payload.json:

{
  "userId": "usr_self"
}

CLI:

topolo actions validate app_topolo_auth.sessions.list --data @payload.json --json
topolo actions plan app_topolo_auth.sessions.list --data @payload.json --json
topolo actions call app_topolo_auth.sessions.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.sessions.list",
    "input": {
      "userId": "usr_self"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Sessions fetched",
  "data": {
    "sessions": [
      {
        "id": "session_current",
        "user_id": "usr_self",
        "organization_id": "org_example",
        "context_type": null,
        "context_id": null,
        "device_info": {
          "browser": "Fixture Browser"
        },
        "ip_address": null,
        "user_agent": null,
        "created_at": 1790899190,
        "last_activity": 1790899200,
        "expires_at": 1790902800,
        "status": "active"
      }
    ]
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

All sessions includes expired active and revoked rows without pagination

Input · payload.json:

{
  "userId": "usr_self",
  "status": "all"
}

CLI:

topolo actions validate app_topolo_auth.sessions.list --data @payload.json --json
topolo actions plan app_topolo_auth.sessions.list --data @payload.json --json
topolo actions call app_topolo_auth.sessions.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.sessions.list",
    "input": {
      "userId": "usr_self",
      "status": "all"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Sessions fetched",
  "data": {
    "sessions": [
      {
        "id": "session_current",
        "user_id": "usr_self",
        "organization_id": "org_example",
        "context_type": null,
        "context_id": null,
        "device_info": {
          "browser": "Fixture Browser"
        },
        "ip_address": null,
        "user_agent": null,
        "created_at": 1790899190,
        "last_activity": 1790899200,
        "expires_at": 1790902800,
        "status": "active"
      },
      {
        "id": "session_revoked",
        "user_id": "usr_self",
        "organization_id": "org_example",
        "context_type": null,
        "context_id": null,
        "device_info": {},
        "ip_address": null,
        "user_agent": null,
        "created_at": 1790899190,
        "last_activity": 1790899195,
        "expires_at": 1790902800,
        "status": "revoked"
      },
      {
        "id": "session_old",
        "user_id": "usr_self",
        "organization_id": "org_example",
        "context_type": null,
        "context_id": null,
        "device_info": {
          "browser": "Fixture Browser"
        },
        "ip_address": null,
        "user_agent": null,
        "created_at": 1790899190,
        "last_activity": 1790899190,
        "expires_at": 1790899199,
        "status": "active"
      }
    ]
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Revoked list uses stored status and malformed device data becomes empty object

Input · payload.json:

{
  "userId": "usr_self",
  "status": "revoked"
}

CLI:

topolo actions validate app_topolo_auth.sessions.list --data @payload.json --json
topolo actions plan app_topolo_auth.sessions.list --data @payload.json --json
topolo actions call app_topolo_auth.sessions.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.sessions.list",
    "input": {
      "userId": "usr_self",
      "status": "revoked"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Sessions fetched",
  "data": {
    "sessions": [
      {
        "id": "session_revoked",
        "user_id": "usr_self",
        "organization_id": "org_example",
        "context_type": null,
        "context_id": null,
        "device_info": {},
        "ip_address": null,
        "user_agent": null,
        "created_at": 1790899190,
        "last_activity": 1790899195,
        "expires_at": 1790902800,
        "status": "revoked"
      }
    ]
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Organization administrator reads the authorized managed user

Input · payload.json:

{
  "userId": "usr_managed"
}

CLI:

topolo actions validate app_topolo_auth.sessions.list --data @payload.json --json
topolo actions plan app_topolo_auth.sessions.list --data @payload.json --json
topolo actions call app_topolo_auth.sessions.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.sessions.list",
    "input": {
      "userId": "usr_managed"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Sessions fetched",
  "data": {
    "sessions": [
      {
        "id": "session_managed",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "context_type": null,
        "context_id": null,
        "device_info": {
          "browser": "Fixture Browser"
        },
        "ip_address": null,
        "user_agent": null,
        "created_at": 1790899190,
        "last_activity": 1790899200,
        "expires_at": 1790902800,
        "status": "active"
      }
    ]
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Current repository maps a SQL read failure to an empty successful list

Input · payload.json:

{
  "userId": "usr_self"
}

CLI:

topolo actions validate app_topolo_auth.sessions.list --data @payload.json --json
topolo actions plan app_topolo_auth.sessions.list --data @payload.json --json
topolo actions call app_topolo_auth.sessions.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.sessions.list",
    "input": {
      "userId": "usr_self"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Sessions fetched",
  "data": {
    "sessions": []
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Verify the result

Use each returned id only with its user_id and the exact authorized target. Compare status and expires_at; all has no continuation and can return expired rows.
If storage failure is suspected, preserve evidence and verify store health through the authorized operator rather than equating an empty successful response with no sessions.

Errors and recovery

Admin cannot read a user outside its organization

Captured local refusal · HTTP 403:

{
  "input": {
    "userId": "usr_foreign"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Insufficient permissions",
      "code": "FORBIDDEN",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Undiscoverable managed user is refused

Captured local refusal · HTTP 403:

{
  "input": {
    "userId": "usr_missing"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Insufficient permissions",
      "code": "FORBIDDEN",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Anonymous session read is refused

Captured local refusal · HTTP 401:

{
  "input": {
    "userId": "usr_self"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access token required",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Invalid token is a current server error

Captured local refusal · HTTP 500:

{
  "input": {
    "userId": "usr_self"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Invalid fixture token",
      "code": "SERVER_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Published recovery guidance

AUTH_ERROR (HTTP 401): Verify the intended identity and access-token transport. Refresh only an expired credential for that same approved context; do not switch organizations automatically.
FORBIDDEN (HTTP 403): Verify target-user authority in the selected organization. Preserve the denial; session ids cannot authorize access to a different user.
SERVER_ERROR (HTTP 500): Inspect the original error and current state. Invalid-token exceptions can return 500. A recovery write or token-version bump may already have happened; do not blindly repeat a mutation or claim a delivery/revocation outcome.

Recovery boundaries

Read-only. Refresh target-user discovery and authority; keep device/network/session security data within the authorized workflow.

Discovery and evidence

This record belongs to app_topolo_auth. Local tests prove real canonical session/recovery email SQL, target-user authorization and handler responses with simulated tokens, identity lookup and Notify results. Verification state is seeded; tokens are unusable. They do not prove live JWT rejection, browser OAuth recovery, email delivery, recipient verification, deployment or production completion.