Skip to main content

​
Overview

A Member Session begins after an end user meets the primary and secondary factor authentication requirements of an Organization. In cases where an authentication call does not satisfy the Organization’s requirements, an intermediate session is returned. This will be exchanged for a full session after the authentication flow is completed:

Intermediate session

Begins if an end user has started a primary factor authentication, but isn’t fully authenticated into an organization yet.

Full session

Begins once an end user has completed all required authentication factors for an organization.

​
Intermediate session

An intermediate session begins when an intermediate_session_token is returned after a primary factor authenticate() call or a discovery authentication call. It represents a temporary authentication session state of a user that hasn’t been fully authenticated into an organization yet.

​
Attributes

  • No organizational context
    Intermediate sessions aren’t associated with any organization. A user must meet all primary and secondary authentication factors for an organization for the token to be successfully exchanged for a full Member Session with an organization.
  • Fixed intermediate session duration
    Intermediate session tokens are valid for 10 minutes. If the token is not exchanged for a Member Session before expiration, the end user must restart the authentication process.
  • Using intermediate sessions
    Intermediate sessions are used during an authentication flow to facilitate step-up primary authentication, multi-factor authentication (MFA), and the Discovery login experience.

​
Additional resources

Intermediate sessions in authentication

​
Full member session

A full member session is initiated after a successful authentication call that satisfies all of an Organization’s authentication requirements. This could be directly from an authenticate() call (e.g. magic links) for an org-specific login, from an intermediate session token exchange after a Discovery flow, or from a secondary factor authentication call (e.g. SMS OTP) for an organization that requires MFA. These methods generate a newly minted Member Session object in the response, containing useful attributes about the member’s logged in state that can be stored as part of your application logic.
Response 200
{
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200,
	"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
	"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
	"session_jwt": "eyJ...",
	"intermediate_session_token": "",
	"member_authenticated": true,
	"mfa_required": null,
	"primary_required", null,
    "member_session": {...},
    "member": {...},
    "organization": {...}
}
Object 200
{
  "member_session": {
    "member_session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "started_at": "2023-01-09T07:41:52Z",
    "last_accessed_at": "2023-01-09T07:41:52Z",
    "expires_at": "2021-08-10T07:41:52Z",
    "authentication_factors": [
      {
        "delivery_method": "email",
        "email_factor": {
          "email_address": "sandbox@stytch.com",
          "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
        },
        "last_authenticated_at": "2023-01-09T07:41:52Z",
        "created_at": "2023-01-09T07:41:52Z",
        "updated_at": "2023-01-09T07:41:52Z",
        "sequence_order": "PRIMARY",
        "type": "magic_link"
      }
    ],
    "custom_claims": {
      "claim1": "value1",
      "claim2": "value2"
    },
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "roles": ["stytch_member", "editor"]
  }
}

​
Attributes

  • Associated to organizations
    A full session is always associated with a specific organization_id.
  • Configurable session duration
    The default duration of a session is 60 minutes, which can be configured in the call initiating a session via session_duration_minutes.
  • Identifying and using sessions
    Sessions are identified by a session_token and session_jwt, which are used to authenticate and authorize requests between your client and server.

​
Additional resources

Member session object

​
Intermediate to full session lifecycle example

This illustrates an org-specific login sequence where the organization requires a secondary authentication factor (MFA):