--- title: "List sessions" method: GET path: "/zones/{zoneId}/sessions" tags: ["Sessions"] --- # List sessions `GET /zones/{zoneId}/sessions` ## Request - Base URL: `https://docs.keycard.ai` (the document declares no server; this is the origin it was published from) - URL: `https://docs.keycard.ai/zones/{zoneId}/sessions` - Auth: one of: - HTTP bearer - OAuth 2 - Client credentials - Token URL: `/service-account-token` 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. - `external` boolean, required: Whether the user is synced from an external directory over SCIM. When true the user is directory-owned: `status` cannot be changed and the user cannot be deleted through this API while the zone has `external_sync_enabled` set. - `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: Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text. - `role_owner_type` 'platform' | 'customer', required: Owner type of the granted role. Disambiguates roles that share an identifier across owner types. - `scope` object, nullable, required: The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself). - … - `source` 'user' | 'group', required: The principal that holds this grant: `user` when assigned directly to the user, or `group` when inherited through group membership. - `group_id` string: ID of the group this grant is inherited from. Present only when `source` is `group`. - `groups` IamUserGroup[]: Groups this user belongs to within the zone. Populated only when `expand[]=groups` is set on the listing endpoint. - `id` string, required: Unique identifier of the group - `identifier` string, required: Zone-unique slug that policy rules match on. - `name` string, required: Human-readable group name - `external` boolean, required: Whether the group is synced from an external directory. When true the group is directory-owned and its membership is read-only; when false it is managed in Keycard. - `external_issuer` string, nullable, required: Issuer of the external directory the group was synced from. `null` for groups managed in Keycard. Read-only: set by external sync, never by the caller. - `credentials` IamUserCredential[]: Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when `expand[]=credentials` is set on the listing endpoint. - union: An authentication credential belonging to a user. - … - `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 - `400`: Error response - `404`: Error response - `default`: Error response ## Changes - **2026-10-16** `0cfaff865771`: 1 warning, 3 info - removed the optional property `items/items/allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/credentials/items/anyOf[subschema #1: User Credential Federation]/allOf[subschema #2]/provider/allOf[subschema #1: Provider]/protocols/openid/external_id_claim` from the response with the `200` status - added the required property `items/items/allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/external` to the response with the `200` status - added the required property `items/items/allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/groups/items/external` to the response with the `200` status - added the required property `items/items/allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/groups/items/external_issuer` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/changes/zones/:zoneId/sessions/get.md) --- [API](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api.md) - [All operations](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/revisions/0dee67e0a73a?raw)