The Stytch Session object contains all of the information about a user's session; when it was started, when it expires, which authentication factors were validated, e.g. password, OAuth, OTP, etc. Read more about Stytch Sessions and how they work in our Sessions guide.
Session object
Fields
attributes object
Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application.
ip_address string
The IP address of the client.
user_agent string
The user agent of the client.
authentication_factors array[objects]
An array of different authentication factors that comprise a Session.
created_at timestamp
The timestamp when the factor was initially authenticated.
delivery_method string
The method that was used to deliver the authentication factor. The possible values are: email. sms whatsapp embedded oauth_google: All OAuth providers are in this pattern, e.g. oauth_microsoft, oauth_figma, etc. knowledge: For passwords. webauthn_registration: For WebAuthn or Passkeys. authenticator_app: For normal TOTP flow. recovery_code: For TOTP recovery codes. crypto_wallet biometric: For Native Mobile Biometrics. imported_auth0: For a zero downtime migrated session from Auth0. impersonation oauth_access_token_exchange: For OAuth access token exchange in our Connected Apps product.
last_authenticated_at timestamp
The timestamp when the factor was last authenticated.
email_factor object
Information about the email factor, if one is present.
email_address string
The email address of the User.
email_id string
The globally unique UUID of the User's email address.
phone_number_factor object
Information about the phone number factor, if one is present.
phone_number string
The phone number of the User.
phone_id string
The globally unique UUID of the User's phone number.
<PROVIDER>_oauth_factor object
Information about the OAuth factor, if one is present. Note that OAuth factors are in this pattern, e.g. google_oauth_factor, microsoft_oauth_factor, etc.
email_id string
The globally unique UUID of the User's email.
id string
The globally unique UUID of the User's OAuth registration.
provider_subject string
The user's unique identifier from the Identity Provider, e.g. Google, Apple, etc.
type string
The type of authentication factor. The possible values are: magic_link otp: SMS or WhatsApp. email_otp oauth password signature_challenge Native Mobile Biometrics. webauthn: WebAuthn or Passkeys. totp crypto_wallet recovery_codes: For sessions in a TOTP recovery state. impersonated imported: For imported, zero downtime migrated sessions from a third party provider.
updated_at timestamp
The timestamp when the factor was last updated.
impersonated_factor object
Information about the impersonated factor, if one is present.
impersonator_email_address string
The email address of the impersonator.
impersonator_id string
For impersonated sessions initiated via the Stytch Dashboard, the impersonator_id will be the impersonator's Stytch Dashboard member_id.
custom_claims array[objects]
A custom claims map for the Session being authenticated. Claims will be included on the Session object and in the JWT. iss, sub, aud, exp, nbf, iat, jti are reserved claims. Total custom claims size cannot exceed four kilobytes.
expires_at timestamp
The timestamp when the Session will expire. Once a session is expired, it is no longer valid and Stytch will return a 404 error if it is authenticated.
last_accessed_at timestamp
The timestamp when the Session was last accessed. A session is considered accessed when it is authenticated with the Stytch API, local JWT authentication will not iterate this value.
session_id string
A unique identifier for a specific Session.
started_at timestamp
The timestamp when the Session started.
user_id string
The unique ID of a specific User. You may use an external_id here if one is set for the user.
OBJECT 200
{
"session": {
"attributes": {
"ip_address": "",
"user_agent": ""
},
"authentication_factors": [
{
"created_at": "2025-01-09T07:41:52Z",
"delivery_method": "email",
"email_factor": {
"email_address": "sandbox@stytch.com",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
},
"last_authenticated_at": "2025-01-09T07:41:52Z",
"updated_at": "2025-01-09T07:41:52Z",
"type": "magic_link"
},
{
"created_at": "2025-01-09T08:41:52Z",
"delivery_method": "knowledge",
"last_authenticated_at": "2025-01-09T08:41:52Z",
"type": "password",
"updated_at": "2025-01-09T08:41:52Z"
}
],
"custom_claims": {
"claim1": "value1",
"claim2": "value2"
},
"expires_at": "2025-04-22T08:00:00Z",
"last_accessed_at": "2025-04-22T07:41:52Z",
"started_at": "2025-04-22T07:00:00Z",
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}
}