Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
List an IAM user's live sessions
Returns the sessions that are LIVE for the selected user right now, newest first, each
carrying the non-secret sid that iam.user.revoke (target session) takes. This is the
operator's view of somebody else's sessions; the user's own equivalent is
GET /api/v1/auth/sessions, which returns the same row plus current.
Sessions live in auth-go, not in this database — there is no local session store to
enumerate — so this read is served from GET /internal/sessions?accountId=… keyed by the
user's email (auth-go's account id).
Validation: scopeId must be a scope the caller can access and userId must identify a
user visible in that scope — unknown or out-of-scope ids return 404 via ErrNotFound. A user
who exists but has no open session is 200 with an EMPTY array, never 404: "signed in nowhere"
is a real answer, and answering 404 would leak the difference between an unknown user and an
idle one.
Async & state: Synchronous read; no state change. Not cacheable — the list is live.
Errors: 401 when unauthenticated; 403 when the caller lacks an IAM-read-capable role on the
scope; 404 when scopeId/userId is unknown; 500 when auth-go is unreachable, throttled or
erroring. It FAILS CLOSED and never degrades to an empty list: an empty list reads as "this
user is signed in nowhere", which is exactly the wrong thing to show an operator deciding
whether to cut somebody's access during an incident.
Idempotency/Concurrency: Safe; no idempotency key. Session tokens (the cookie secret) are
never present — only sid, which is safe to display and is the revoke key.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
userId*stringIdentifier of the IAM user.
page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200). Lists that used to return every row default to the maximum, so a client that does not page keeps seeing up to 200 rows; a larger value is refused with 422.
1 <= value <= 200200The user's live sessions, newest first; empty when none are open.
application/json- response
[index: integer]?One LIVE session of an IAM user, as auth-go holds it. ip and userAgent are the values auth-go stored, VERBATIM. Beside them (never instead of them) auth-go derives two display aids at read time: device, parsed locally from userAgent (an unrecognised signature is type: unknown with empty strings — never a guess), and location, an APPROXIMATE place looked up in an OFFLINE GeoIP database inside auth-go (DB-IP Lite, CC BY 4.0; no third-party call, the IP never leaves the platform). location is null when auth-go has no GeoIP database loaded. ip, userAgent and lastSeenAt are genuinely nullable; render an em dash, not a placeholder — none of them is ever a string standing in for "we do not know". Timestamps are offset-aware RFC 3339 and are NOT guaranteed to end in Z: auth-go renders timestamptz in its own session timezone, so parse them, never string-match the suffix. The client-portal row (GET /api/v1/auth/sessions) is this same shape plus current; an operator looking at somebody else's sessions has no "this is you" row, so current is absent here rather than always false.
curl -X GET "https://example.com/scopes/string/iam/users/string/sessions"[ { "sid": "string", "createdAt": "2019-08-24T14:15:22Z", "lastSeenAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "authTime": "2019-08-24T14:15:22Z", "amr": [ "string" ], "acr": "string", "idp": "string", "ip": "string", "userAgent": "string", "device": { "browser": "string", "browserVersion": "string", "os": "string", "osVersion": "string", "type": "desktop" }, "location": { "city": "string", "region": "string", "country": "string", "countryCode": "string", "kind": "public" } }]