--- title: "Update session" method: PATCH path: "/zones/{zoneId}/sessions/{id}" tags: ["Sessions"] --- # Update session `PATCH /zones/{zoneId}/sessions/{id}` Revokes an active session ## Path parameters - `zoneId` string, required - `id` string, required ## Request body - object - `status` 'revoked', required ## Response `200` An authenticated identity session. Sessions can be user sessions (representing end-user authentication) or application sessions (representing service-to-service authentication). User sessions support hierarchical relationships via parent_id, while application sessions are always standalone. - 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 — 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). - `type` string, required — The kind of resource this grant is scoped to (e.g. `zone`). - `id` string, required — The ID of the scoped resource. - `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 - `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. - IamUserCredentialFederation — Common fields shared by all user credential types - `created_at` string, date-time, required — Entity creation timestamp - `updated_at` string, date-time, required — Entity update timestamp - `type` 'federation', required - `subject` string — Subject identifier from the identity provider. - `issuer` string — Issuer identifier of the identity provider. - `provider_id` string, nullable, required — ID of the identity provider backing this credential. `null` when the source provider has been deleted. - `provider` IamProvider — A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. - … - IamUserCredentialPassword — Common fields shared by all user credential types - `created_at` string, date-time, required — Entity creation timestamp - `updated_at` string, date-time, required — Entity update timestamp - `type` 'password', required - `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 - `redirect_uris` string[], nullable — OAuth 2.0 redirect URIs for this application - `post_logout_redirect_uris` string[], nullable — OAuth 2.0 post-logout redirect URIs for this application - `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 - `redirect_uris` string[], nullable — OAuth 2.0 redirect URIs for this application - `post_logout_redirect_uris` string[], nullable — OAuth 2.0 post-logout redirect URIs for this application - `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 ## Other responses - `400` — Error response - `404` — Error response - `default` — Error response ## Changes - **2026-08-26** `d65d51379d93` — 8 info - added the non-success response with the status `400` - added the non-success response with the status `404` - added the optional property `allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/credentials` to the response with the `200` status - added the optional property `allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/groups` to the response with the `200` status - …4 more - **2026-07-01** `2f5033ed4491` — 2 info - added the optional property `allOf[subschema #2]/anyOf[subschema #1: User Session Type]/application/allOf[subschema #1: Application]/metadata/icon_url` to the response with the `200` status - added the optional property `allOf[subschema #2]/anyOf[subschema #2: Application Session Type]/application/allOf[subschema #1: Application]/metadata/icon_url` to the response with the `200` status - **2026-06-17** `1a0dd4d857ee` — 1 info - added the required property `allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/status` to the response with the `200` status - **2026-06-09** `7e0e4fa2e16f` — 1 info - added the optional property `allOf[subschema #2]/anyOf[subschema #1: User Session Type]/user/allOf[subschema #1: User]/role_assignments` to the response with the `200` status - …earlier changes not shown [Full history](https://skmtc.dev/keycardai/apis/untitled-api/changes/zones/:zoneId/sessions/:id/patch.md) --- [API](https://skmtc.dev/keycardai/apis/untitled-api.md) · [All operations](https://skmtc.dev/keycardai/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/keycardai/untitled-api/revisions/d65d51379d93/schema)