--- title: "List sessions" method: GET path: "/zones/{zoneId}/sessions" tags: ["Sessions"] --- # List sessions `GET /zones/{zoneId}/sessions` Returns sessions in the specified zone. By default, returns entry sessions (app user sessions with an initiator that are roots or direct children of a root user session). Use include_nested=true to include nested sessions. Can be filtered by session type, status, and user. ## Path parameters - `zoneId` string, required ## Query parameters - `session_type` 'user' | 'application' - `active` 'true' - `status` 'active' | 'expired' | 'revoked' - `user_id` string - `include_nested` 'true' - `after` string - `before` string - `limit` integer - `expand[]` union - 'total_count' - string[] ## Response `200` Default Response - object - `items` IamSession[], required - union - object — User session type-specific fields - `id` string, required — Session ID - `organization_id` string, required — Organization that owns this session - `zone_id` string, required — Zone this session belongs to - `created_at` string, date-time, required — Entity creation timestamp - `authenticated_at` string, date-time — Date when the session was authenticated - `updated_at` string, date-time, required — Entity update timestamp - `expires_at` string, date-time, required — Date when session expires - `session_data` object — Session claims data (ID token claims for users, application claims for applications) - `metadata` object, required — Session metadata - `name` string, required — Name of the initiating application or user agent - `status` 'active' | 'expired' | 'revoked' - `active` boolean — Whether the session is currently active (deprecated - use status instead) - `session_type` 'user', required - `user_id` string, required — User ID - `application_id` string — Application ID that initiated this session - `user_agent_id` string — User agent ID (browser/client) that initiated this session - `user` IamUser — An authenticated user entity - `id` string, required — Unique identifier of the user - `organization_id` string, required — Organization that owns this user - `zone_id` string, required — Zone this user belongs to - `identifier` string, required — Zone-scoped user identifier. Defaults to the user's Keycard ID. When the provider has user_identifier_claim configured, the value is set from that claim at user creation time. - `subject` string — Subject identifier from the identity provider - `issuer` string — Issuer identifier of the identity provider - `email` string, email, required — Email address of the user - `email_verified` boolean, required — Whether the email address has been verified - `status` 'active' | 'disabled', required — Status of the user. Disabled users cannot authenticate. - `provider_id` string — Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted. - `created_at` string, date-time, required — Entity creation timestamp - `updated_at` string, date-time, required — Entity update timestamp - `authenticated_at` string — Date when the user was last authenticated - `session_count` integer — Session count for this user. Populated only when `expand[]=session_count` is set on the listing endpoint. - `grant_count` integer — Delegated-grant count for this user. Populated only when `expand[]=grant_count` is set on the listing endpoint. - `role_assignments` IamUserRoleAssignment[] — Role grants for this user within the zone. Populated only when `expand[]=role-assignments` is set on the listing endpoint. - `role_id` string, required — ID of the assigned role - `role_identifier` string, required — Opaque role identifier. Treated as an opaque identifier by the API and unique within a zone. - `scope` object, nullable, required — The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself). - … - `application` IamApplication — An Application is a software system with an associated identity that can access Resources. It may act on its own behalf (machine-to-machine) or on behalf of a user (delegated access). - `id` string, required — Unique identifier of the application - `organization_id` string, required — Organization that owns this application - `zone_id` string, required — Zone this application belongs to - `slug` string, required — URL-safe identifier, unique within the zone - `identifier` string, required — User specified identifier, unique within the zone - `name` string, required — Human-readable name - `description` string, nullable — Human-readable description - `metadata` IamMetadata — Entity metadata - `docs_url` string, uri — Documentation URL - `icon_url` string, uri — Icon URL - `protocols` object, nullable — Protocol-specific configuration - `oauth2` IamApplicationOAuth2Protocol, nullable — OAuth 2.0 protocol configuration - … - `dependencies_count` integer, required — Number of resource dependencies - `owner_type` 'platform' | 'customer', required — Who owns this application. Platform-owned applications cannot be modified via API. - `consent` 'implicit' | 'required', required — Consent mode for the application. 'implicit' means consent is automatically granted, 'required' means explicit user consent is needed. - `created_at` string, date-time, required — Entity creation timestamp - `updated_at` string, date-time, required — Entity update timestamp - `user_agent` IamUserAgent — A User Agent represents a user agent (browser, desktop app, CLI tool) that can initiate user sessions via OAuth 2.0 Dynamic Client Registration. - `id` string, required — Unique identifier of the user agent - `organization_id` string, required — Organization that owns this user agent - `zone_id` string, required — Zone this user agent belongs to - `slug` string, required — URL-safe identifier, unique within the zone - `identifier` string, required — User agent identifier (serves as OAuth client_id). Format: ua:{sha256_hash} - `name` string, required — Human-readable name - `created_at` string, date-time, required — Entity creation timestamp - `updated_at` string, date-time, required — Entity update timestamp - `provider_id` string — Provider ID - `subject` string — Subject claim from IdP - `issuer` string, uri — Issuer URL from IdP - `parent_id` string — Parent session ID for hierarchical sessions (user sessions only). When null, this is a web session - a top-level session initiated directly by a user. When set, this is a child session derived from the parent, used for token refresh or delegation. Application sessions cannot have parents. - object — Application session type-specific fields - `id` string, required — Session ID - `organization_id` string, required — Organization that owns this session - `zone_id` string, required — Zone this session belongs to - `created_at` string, date-time, required — Entity creation timestamp - `authenticated_at` string, date-time — Date when the session was authenticated - `updated_at` string, date-time, required — Entity update timestamp - `expires_at` string, date-time, required — Date when session expires - `session_data` object — Session claims data (ID token claims for users, application claims for applications) - `metadata` object, required — Session metadata - `name` string, required — Name of the initiating application or user agent - `status` 'active' | 'expired' | 'revoked' - `active` boolean — Whether the session is currently active (deprecated - use status instead) - `session_type` 'application', required - `application_id` string, required — Application ID that initiated this session - `application` IamApplication — An Application is a software system with an associated identity that can access Resources. It may act on its own behalf (machine-to-machine) or on behalf of a user (delegated access). - `id` string, required — Unique identifier of the application - `organization_id` string, required — Organization that owns this application - `zone_id` string, required — Zone this application belongs to - `slug` string, required — URL-safe identifier, unique within the zone - `identifier` string, required — User specified identifier, unique within the zone - `name` string, required — Human-readable name - `description` string, nullable — Human-readable description - `metadata` IamMetadata — Entity metadata - `docs_url` string, uri — Documentation URL - `icon_url` string, uri — Icon URL - `protocols` object, nullable — Protocol-specific configuration - `oauth2` IamApplicationOAuth2Protocol, nullable — OAuth 2.0 protocol configuration - … - `dependencies_count` integer, required — Number of resource dependencies - `owner_type` 'platform' | 'customer', required — Who owns this application. Platform-owned applications cannot be modified via API. - `consent` 'implicit' | 'required', required — Consent mode for the application. 'implicit' means consent is automatically granted, 'required' means explicit user consent is needed. - `created_at` string, date-time, required — Entity creation timestamp - `updated_at` string, date-time, required — Entity update timestamp - `provider_id` string, required — Provider ID - `subject` string, required — Subject claim from IdP - `issuer` string, uri, required — Issuer URL from IdP - `pagination` IamPagination, required — Cursor-based pagination metadata - `after_cursor` string, required — An opaque cursor used for paginating through a list of results - `before_cursor` string, required — An opaque cursor used for paginating through a list of results - `total_count` integer — Total number of items matching the query. Only included when expand[]=total_count is requested. ## Other responses - `default` — Error response --- [API](https://skmtc.net/keycardai/apis/untitled-api.md) · [All operations](https://skmtc.net/keycardai/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keycardai/untitled-api/revisions/2f5033ed4491/schema)