Skip to content
Docs
Sessions
Retrieve

Get session

API Reference
Zones
Sessions

Get session

zones.sessions.retrieve(strid, SessionRetrieveParams**kwargs) -> Session
GET/zones/{zoneId}/sessions/{id}

Returns details of a specific session by session ID

ParametersExpand Collapse
zone_id: str
id: str
ReturnsExpand Collapse
Session

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.

Accepts one of the following:
class IamUserSessionType: …

User session type-specific fields

session_type: Literal["user"]
user_id: str

User ID

id: Optional[str]

Session ID

Deprecatedactive: Optional[bool]

Whether the session is currently active (deprecated - use status instead)

Deprecatedapplication: Optional[Application]

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: str

Unique identifier of the application

Accepts one of the following:
created_at: datetime

Entity creation timestamp

formatdate-time
dependencies_count: int

Number of resource dependencies

identifier: str

User specified identifier, unique within the zone

minLength1
maxLength2048
name: str

Human-readable name

minLength1
maxLength255
organization_id: str

Organization that owns this application

owner_type: Literal["platform", "customer"]

Who owns this application. Platform-owned applications cannot be modified via API.

Accepts one of the following:
"platform"
"customer"
slug: str

URL-safe identifier, unique within the zone

minLength1
maxLength63
updated_at: datetime

Entity update timestamp

formatdate-time
zone_id: str

Zone this application belongs to

description: Optional[str]

Human-readable description

maxLength2048
metadata: Optional[Metadata]

Entity metadata

docs_url: Optional[str]

Documentation URL

formaturi
maxLength2048
icon_url: Optional[str]

Icon URL

formaturi
maxLength2048
protocols: Optional[Protocols]

Protocol-specific configuration

oauth2: Optional[ProtocolsOauth2]

OAuth 2.0 protocol configuration

post_logout_redirect_uris: Optional[List[str]]

OAuth 2.0 post-logout redirect URIs for this application

redirect_uris: Optional[List[str]]

OAuth 2.0 redirect URIs for this application

application_id: Optional[str]

Application ID that initiated this session

authenticated_at: Optional[datetime]

Date when the session was authenticated

formatdate-time
created_at: Optional[datetime]

Entity creation timestamp

formatdate-time
expires_at: Optional[datetime]

Date when session expires

formatdate-time
issuer: Optional[str]

Issuer URL from IdP

formaturi
metadata: Optional[IamUserSessionTypeMetadata]

Session metadata

name: str

Name of the initiating application or user agent

organization_id: Optional[str]

Organization that owns this session

parent_id: Optional[str]

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.

provider_id: Optional[str]

Provider ID

session_data: Optional[Dict[str, object]]

Session claims data (ID token claims for users, application claims for applications)

status: Optional[Literal["active", "expired", "revoked"]]
Accepts one of the following:
"active"
"expired"
"revoked"
subject: Optional[str]

Subject claim from IdP

updated_at: Optional[datetime]

Entity update timestamp

formatdate-time
Deprecateduser: Optional[User]

An authenticated user entity

id: str

Unique identifier of the user

created_at: datetime

Entity creation timestamp

formatdate-time
email: str

Email address of the user

formatemail
email_verified: bool

Whether the email address has been verified

identifier: str

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.

organization_id: str

Organization that owns this user

status: Literal["active", "disabled"]

Status of the user. Disabled users cannot authenticate.

Accepts one of the following:
"active"
"disabled"
updated_at: datetime

Entity update timestamp

formatdate-time
zone_id: str

Zone this user belongs to

authenticated_at: Optional[str]

Date when the user was last authenticated

credentials: Optional[List[Credential]]

Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when expand[]=credentials is set on the listing endpoint.

Accepts one of the following:
class CredentialIamUserCredentialFederation: …

Federation credential: the user authenticates through an identity provider.

created_at: datetime

Entity creation timestamp

formatdate-time
provider_id: Optional[str]

ID of the identity provider backing this credential. null when the source provider has been deleted.

type: Literal["federation"]
updated_at: datetime

Entity update timestamp

formatdate-time
issuer: Optional[str]

Issuer identifier of the identity provider.

provider: Optional[Provider]

A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate.

id: str

Unique identifier of the provider

created_at: datetime

Entity creation timestamp

formatdate-time
identifier: str

User specified identifier, unique within the zone

minLength1
maxLength2048
name: str

Human-readable name

minLength1
maxLength255
organization_id: str

Organization that owns this provider

owner_type: Literal["platform", "customer"]

Who owns this provider. Platform-owned providers cannot be modified via API.

Accepts one of the following:
"platform"
"customer"
slug: str

URL-safe identifier, unique within the zone

minLength1
maxLength63
updated_at: datetime

Entity update timestamp

formatdate-time
zone_id: str

Zone this provider belongs to

client_id: Optional[str]

OAuth 2.0 client identifier

client_secret_set: Optional[bool]

Indicates whether a client secret is configured

description: Optional[str]

Human-readable description

maxLength2048
metadata: Optional[Metadata]

Provider metadata

icon_url: Optional[str]

Icon URL

formaturi
maxLength2048
protocols: Optional[Protocols]

Protocol-specific configuration

oauth2: Optional[ProtocolsOauth2]

OAuth 2.0 protocol configuration

issuer: str

OIDC issuer URL used for discovery and token validation.

formaturi
authorization_endpoint: Optional[str]
formaturi
authorization_parameters: Optional[Dict[str, str]]

Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline).

authorization_resource_enabled: Optional[bool]

Whether to include the resource parameter in authorization requests.

authorization_resource_parameter: Optional[str]

The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true.

code_challenge_methods_supported: Optional[List[str]]
jwks_uri: Optional[str]
formaturi
registration_endpoint: Optional[str]
formaturi
scope_parameter: Optional[str]

The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope".

scope_separator: Optional[str]

The separator character for scope values. Defaults to " " (space). Slack v2 uses ",".

scopes_supported: Optional[List[str]]
token_endpoint: Optional[str]
formaturi
token_response_access_token_pointer: Optional[str]

Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token".

openid: Optional[ProtocolsOpenid]

OpenID Connect protocol configuration

external_id_claim: Optional[str]

Name of the OIDC claim carrying the stable external id used to correlate logins with externally provisioned (SCIM) users. Defaults to "sub". Set to "oid" for Entra, whose pairwise "sub" differs from the SCIM externalId.

scopes: Optional[List[str]]

Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email).

single_logout_enabled: Optional[bool]

When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false.

user_identifier_claim: Optional[str]

Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. When not set, the user's Keycard ID is used.

userinfo_endpoint: Optional[str]
formaturi
type: Optional[Literal["external", "keycard-vault", "keycard-sts"]]
Accepts one of the following:
"external"
"keycard-vault"
"keycard-sts"
subject: Optional[str]

Subject identifier from the identity provider.

class CredentialIamUserCredentialPassword: …

Password credential: the user authenticates with email and password. The email lives on the user.

created_at: datetime

Entity creation timestamp

formatdate-time
type: Literal["password"]
updated_at: datetime

Entity update timestamp

formatdate-time
grant_count: Optional[int]

Delegated-grant count for this user. Populated only when expand[]=grant_count is set on the listing endpoint.

minimum0
groups: Optional[List[Group]]

Groups this user belongs to within the zone. Populated only when expand[]=groups is set on the listing endpoint.

id: str

Unique identifier of the group

identifier: str

Zone-unique slug that policy rules match on.

name: str

Human-readable group name

issuer: Optional[str]

Issuer identifier of the identity provider

provider_id: Optional[str]

Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted.

role_assignments: Optional[List[RoleAssignment]]

Role grants for this user within the zone. Populated only when expand[]=role-assignments is set on the listing endpoint.

role_id: str

ID of the assigned role

role_identifier: str

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.

minLength1
maxLength255
role_owner_type: Literal["platform", "customer"]

Owner type of the granted role. Disambiguates roles that share an identifier across owner types.

Accepts one of the following:
"platform"
"customer"
scope: Optional[RoleAssignmentScope]

The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself).

id: str

The ID of the scoped resource.

type: str

The kind of resource this grant is scoped to (e.g. zone).

source: Literal["user", "group"]

The principal that holds this grant: user when assigned directly to the user, or group when inherited through group membership.

Accepts one of the following:
"user"
"group"
group_id: Optional[str]

ID of the group this grant is inherited from. Present only when source is group.

session_count: Optional[int]

Session count for this user. Populated only when expand[]=session_count is set on the listing endpoint.

minimum0
subject: Optional[str]

Subject identifier from the identity provider

Deprecateduser_agent: Optional[UserAgent]

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: str

Unique identifier of the user agent

created_at: datetime

Entity creation timestamp

formatdate-time
identifier: str

User agent identifier (serves as OAuth client_id). Format: ua:{sha256_hash}

name: str

Human-readable name

minLength1
maxLength255
organization_id: str

Organization that owns this user agent

slug: str

URL-safe identifier, unique within the zone

minLength1
maxLength63
updated_at: datetime

Entity update timestamp

formatdate-time
zone_id: str

Zone this user agent belongs to

user_agent_id: Optional[str]

User agent ID (browser/client) that initiated this session

zone_id: Optional[str]

Zone this session belongs to

class IamApplicationSessionType: …

Application session type-specific fields

application_id: str

Application ID that initiated this session

issuer: str

Issuer URL from IdP

formaturi
provider_id: str

Provider ID

session_type: Literal["application"]
subject: str

Subject claim from IdP

id: Optional[str]

Session ID

Deprecatedactive: Optional[bool]

Whether the session is currently active (deprecated - use status instead)

Deprecatedapplication: Optional[Application]

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: str

Unique identifier of the application

Accepts one of the following:
created_at: datetime

Entity creation timestamp

formatdate-time
dependencies_count: int

Number of resource dependencies

identifier: str

User specified identifier, unique within the zone

minLength1
maxLength2048
name: str

Human-readable name

minLength1
maxLength255
organization_id: str

Organization that owns this application

owner_type: Literal["platform", "customer"]

Who owns this application. Platform-owned applications cannot be modified via API.

Accepts one of the following:
"platform"
"customer"
slug: str

URL-safe identifier, unique within the zone

minLength1
maxLength63
updated_at: datetime

Entity update timestamp

formatdate-time
zone_id: str

Zone this application belongs to

description: Optional[str]

Human-readable description

maxLength2048
metadata: Optional[Metadata]

Entity metadata

docs_url: Optional[str]

Documentation URL

formaturi
maxLength2048
icon_url: Optional[str]

Icon URL

formaturi
maxLength2048
protocols: Optional[Protocols]

Protocol-specific configuration

oauth2: Optional[ProtocolsOauth2]

OAuth 2.0 protocol configuration

post_logout_redirect_uris: Optional[List[str]]

OAuth 2.0 post-logout redirect URIs for this application

redirect_uris: Optional[List[str]]

OAuth 2.0 redirect URIs for this application

authenticated_at: Optional[datetime]

Date when the session was authenticated

formatdate-time
created_at: Optional[datetime]

Entity creation timestamp

formatdate-time
expires_at: Optional[datetime]

Date when session expires

formatdate-time
metadata: Optional[IamApplicationSessionTypeMetadata]

Session metadata

name: str

Name of the initiating application or user agent

organization_id: Optional[str]

Organization that owns this session

session_data: Optional[Dict[str, object]]

Session claims data (ID token claims for users, application claims for applications)

status: Optional[Literal["active", "expired", "revoked"]]
Accepts one of the following:
"active"
"expired"
"revoked"
updated_at: Optional[datetime]

Entity update timestamp

formatdate-time
zone_id: Optional[str]

Zone this session belongs to

Get session

import os
from keycardai_api import KeycardAPI

client = KeycardAPI(
    api_key=os.environ.get("KEYCARD_API_API_KEY"),  # This is the default and can be omitted
)
session = client.zones.sessions.retrieve(
    id="id",
    zone_id="zoneId",
)
print(session)
{
  "session_type": "user",
  "user_id": "user_id",
  "id": "id",
  "active": true,
  "application": {
    "id": "id",
    "consent": "implicit",
    "created_at": "2019-12-27T18:11:19.117Z",
    "dependencies_count": 0,
    "identifier": "x",
    "name": "x",
    "organization_id": "organization_id",
    "owner_type": "platform",
    "slug": "slug",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "zone_id": "zone_id",
    "description": "description",
    "metadata": {
      "docs_url": "https://example.com",
      "icon_url": "https://example.com"
    },
    "protocols": {
      "oauth2": {
        "post_logout_redirect_uris": [
          "https://example.com"
        ],
        "redirect_uris": [
          "https://example.com"
        ]
      }
    }
  },
  "application_id": "application_id",
  "authenticated_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "issuer": "https://example.com",
  "metadata": {
    "name": "name"
  },
  "organization_id": "organization_id",
  "parent_id": "parent_id",
  "provider_id": "provider_id",
  "session_data": {
    "foo": "bar"
  },
  "status": "active",
  "subject": "subject",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "user": {
    "id": "id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "email": "dev@stainless.com",
    "email_verified": true,
    "identifier": "identifier",
    "organization_id": "organization_id",
    "status": "active",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "zone_id": "zone_id",
    "authenticated_at": "authenticated_at",
    "credentials": [
      {
        "created_at": "2019-12-27T18:11:19.117Z",
        "provider_id": "provider_id",
        "type": "federation",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "issuer": "issuer",
        "provider": {
          "id": "id",
          "created_at": "2019-12-27T18:11:19.117Z",
          "identifier": "x",
          "name": "x",
          "organization_id": "organization_id",
          "owner_type": "platform",
          "slug": "slug",
          "updated_at": "2019-12-27T18:11:19.117Z",
          "zone_id": "zone_id",
          "client_id": "client_id",
          "client_secret_set": true,
          "description": "description",
          "metadata": {
            "icon_url": "https://example.com"
          },
          "protocols": {
            "oauth2": {
              "issuer": "https://example.com",
              "authorization_endpoint": "https://example.com",
              "authorization_parameters": {
                "foo": "string"
              },
              "authorization_resource_enabled": true,
              "authorization_resource_parameter": "authorization_resource_parameter",
              "code_challenge_methods_supported": [
                "string"
              ],
              "jwks_uri": "https://example.com",
              "registration_endpoint": "https://example.com",
              "scope_parameter": "scope_parameter",
              "scope_separator": "scope_separator",
              "scopes_supported": [
                "string"
              ],
              "token_endpoint": "https://example.com",
              "token_response_access_token_pointer": "token_response_access_token_pointer"
            },
            "openid": {
              "external_id_claim": "external_id_claim",
              "scopes": [
                "string"
              ],
              "single_logout_enabled": true,
              "user_identifier_claim": "user_identifier_claim",
              "userinfo_endpoint": "https://example.com"
            }
          },
          "type": "external"
        },
        "subject": "subject"
      }
    ],
    "grant_count": 0,
    "groups": [
      {
        "id": "id",
        "identifier": "identifier",
        "name": "name"
      }
    ],
    "issuer": "issuer",
    "provider_id": "provider_id",
    "role_assignments": [
      {
        "role_id": "role_id",
        "role_identifier": "role_identifier",
        "role_owner_type": "platform",
        "scope": {
          "id": "id",
          "type": "type"
        },
        "source": "user",
        "group_id": "group_id"
      }
    ],
    "session_count": 0,
    "subject": "subject"
  },
  "user_agent": {
    "id": "id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "identifier": "identifier",
    "name": "x",
    "organization_id": "organization_id",
    "slug": "slug",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "zone_id": "zone_id"
  },
  "user_agent_id": "user_agent_id",
  "zone_id": "zone_id"
}
Returns Examples
{
  "session_type": "user",
  "user_id": "user_id",
  "id": "id",
  "active": true,
  "application": {
    "id": "id",
    "consent": "implicit",
    "created_at": "2019-12-27T18:11:19.117Z",
    "dependencies_count": 0,
    "identifier": "x",
    "name": "x",
    "organization_id": "organization_id",
    "owner_type": "platform",
    "slug": "slug",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "zone_id": "zone_id",
    "description": "description",
    "metadata": {
      "docs_url": "https://example.com",
      "icon_url": "https://example.com"
    },
    "protocols": {
      "oauth2": {
        "post_logout_redirect_uris": [
          "https://example.com"
        ],
        "redirect_uris": [
          "https://example.com"
        ]
      }
    }
  },
  "application_id": "application_id",
  "authenticated_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "issuer": "https://example.com",
  "metadata": {
    "name": "name"
  },
  "organization_id": "organization_id",
  "parent_id": "parent_id",
  "provider_id": "provider_id",
  "session_data": {
    "foo": "bar"
  },
  "status": "active",
  "subject": "subject",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "user": {
    "id": "id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "email": "dev@stainless.com",
    "email_verified": true,
    "identifier": "identifier",
    "organization_id": "organization_id",
    "status": "active",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "zone_id": "zone_id",
    "authenticated_at": "authenticated_at",
    "credentials": [
      {
        "created_at": "2019-12-27T18:11:19.117Z",
        "provider_id": "provider_id",
        "type": "federation",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "issuer": "issuer",
        "provider": {
          "id": "id",
          "created_at": "2019-12-27T18:11:19.117Z",
          "identifier": "x",
          "name": "x",
          "organization_id": "organization_id",
          "owner_type": "platform",
          "slug": "slug",
          "updated_at": "2019-12-27T18:11:19.117Z",
          "zone_id": "zone_id",
          "client_id": "client_id",
          "client_secret_set": true,
          "description": "description",
          "metadata": {
            "icon_url": "https://example.com"
          },
          "protocols": {
            "oauth2": {
              "issuer": "https://example.com",
              "authorization_endpoint": "https://example.com",
              "authorization_parameters": {
                "foo": "string"
              },
              "authorization_resource_enabled": true,
              "authorization_resource_parameter": "authorization_resource_parameter",
              "code_challenge_methods_supported": [
                "string"
              ],
              "jwks_uri": "https://example.com",
              "registration_endpoint": "https://example.com",
              "scope_parameter": "scope_parameter",
              "scope_separator": "scope_separator",
              "scopes_supported": [
                "string"
              ],
              "token_endpoint": "https://example.com",
              "token_response_access_token_pointer": "token_response_access_token_pointer"
            },
            "openid": {
              "external_id_claim": "external_id_claim",
              "scopes": [
                "string"
              ],
              "single_logout_enabled": true,
              "user_identifier_claim": "user_identifier_claim",
              "userinfo_endpoint": "https://example.com"
            }
          },
          "type": "external"
        },
        "subject": "subject"
      }
    ],
    "grant_count": 0,
    "groups": [
      {
        "id": "id",
        "identifier": "identifier",
        "name": "name"
      }
    ],
    "issuer": "issuer",
    "provider_id": "provider_id",
    "role_assignments": [
      {
        "role_id": "role_id",
        "role_identifier": "role_identifier",
        "role_owner_type": "platform",
        "scope": {
          "id": "id",
          "type": "type"
        },
        "source": "user",
        "group_id": "group_id"
      }
    ],
    "session_count": 0,
    "subject": "subject"
  },
  "user_agent": {
    "id": "id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "identifier": "identifier",
    "name": "x",
    "organization_id": "organization_id",
    "slug": "slug",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "zone_id": "zone_id"
  },
  "user_agent_id": "user_agent_id",
  "zone_id": "zone_id"
}