Sessions overview

Sessions represent an authenticated user’s active login to an Organization. After a user successfully authenticates, Stytch creates a Session and returns both a session_token and session_jwt that you can use to authorize requests. Sessions have a configurable lifetime (default: 60 minutes) and can be extended by re-authenticating them before they expire. Sessions contain authentication factors and can be revoked at any time.

Common operations

Authenticate Session
Revoke Session
Get Sessions
Exchange Intermediate Session

Validate a session and optionally extend its lifetime. Use this to authorize requests in your application.

Authenticate with session token

curl --request POST \
  --url https://test.stytch.com/v1/b2b/sessions/authenticate \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "session_duration_minutes": 60
  }'

Parameters:

session_token: The session token to validate (use either this or session_jwt)
session_jwt: Alternative to session_token - the JWT to validate
session_duration_minutes: (Optional) Extend session lifetime by this many minutes
session_custom_claims: (Optional) Custom claims to add to the session JWT
authorization_check: (Optional) Check RBAC permissions during authentication

Response:

{
  "status_code": 200,
  "request_id": "request-id-test-...",
  "member_session": {
    "member_session_id": "member-session-test-...",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "started_at": "2024-01-01T00:00:00Z",
    "last_accessed_at": "2024-01-01T01:00:00Z",
    "expires_at": "2024-01-01T02:00:00Z",
    "authentication_factors": [
      {
        "type": "magic_link",
        "delivery_method": "email",
        "email_factor": {
          "email_id": "email-test-...",
          "email_address": "user@example.com"
        }
      }
    ]
  },
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "session_jwt": "eyJhbGc...",
  "member": { /* member object */ },
  "organization": { /* organization object */ }
}

Use for request authorization

Store the session_token or session_jwt and include it in subsequent requests to verify the user is authenticated. Call the authenticate endpoint on each request or periodically to validate the session is still active.

You can pass an expired JWT (based on its exp claim) and receive a new JWT if the underlying Session is still valid.

Immediately invalidate a session and all its tokens. Use this to implement logout functionality.

Revoke a specific session

curl --request POST \
  --url https://test.stytch.com/v1/b2b/sessions/revoke \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
  }'

Parameters (one required):

session_token: The session token to revoke
session_jwt: Alternative - the session JWT to revoke
member_session_id: Alternative - the session ID to revoke
member_id: Revoke ALL sessions for this member

Response:

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}

Revoke all member sessions

To log a user out of all devices, pass the member_id:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/sessions/revoke \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
  }'

Revoking a session immediately invalidates all tokens. Users will need to re-authenticate.

Retrieve all active sessions for a member.

List member sessions

curl --request GET \
  --url 'https://test.stytch.com/v1/b2b/sessions?organization_id=organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931&member_id=member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f' \
  --user 'PROJECT_ID:SECRET'

Query parameters:

organization_id: The organization’s ID (required)
member_id: The member’s ID (required)

Response:

{
  "status_code": 200,
  "request_id": "request-id-test-...",
  "member_sessions": [
    {
      "member_session_id": "member-session-test-...",
      "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
      "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
      "started_at": "2024-01-01T00:00:00Z",
      "last_accessed_at": "2024-01-01T01:00:00Z",
      "expires_at": "2024-01-01T02:00:00Z",
      "authentication_factors": [
        {
          "type": "magic_link",
          "delivery_method": "email",
          "email_factor": {
            "email_id": "email-test-...",
            "email_address": "user@example.com"
          }
        }
      ]
    }
  ]
}

This endpoint only returns active (non-expired, non-revoked) sessions.

Convert an intermediate session token (from Discovery flow) into a full session for a specific organization.

Exchange the token

After a user completes Discovery authentication and selects an organization, exchange their intermediate session:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/discovery/intermediate_sessions/exchange \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "session_duration_minutes": 60
  }'

Parameters:

intermediate_session_token: The intermediate token to exchange (required)
organization_id: The organization to create a session for (required)
session_duration_minutes: (Optional) Session lifetime in minutes (default: 60)
session_custom_claims: (Optional) Custom claims for the session JWT

Response:

{
  "status_code": 200,
  "request_id": "request-id-test-...",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "session_jwt": "eyJhbGc...",
  "member_authenticated": true,
  "member_session": { /* session object */ },
  "member": { /* member object */ },
  "organization": { /* organization object */ }
}

Handle incomplete authentication

If the user hasn’t satisfied all authentication requirements, member_authenticated will be false:

Check primary_required for required primary auth methods
Check mfa_required for required MFA methods
Complete the required authentication with the intermediate token

Intermediate session tokens are valid for 10 minutes and are used in Discovery flows to allow users to select which organization to log into.

Session tokens vs JWTs

Stytch provides two token formats for sessions:

Session Tokens

Opaque tokens that must be validated server-side via the authenticate endpoint.

More secure (can’t be decoded)
Requires API call to validate
Can be revoked immediately

Session JWTs

JSON Web Tokens that can be validated locally using your project’s public key.

Can validate without API calls
Contains claims (member ID, org ID, etc.)
Slightly delayed revocation (until JWT expires)

Authentication factors

Sessions track which authentication methods were used. Common factors include:

Magic Links - Email-based authentication
OAuth - Social login (Google, Microsoft, etc.)
OTP - One-time passcodes via email or SMS
SSO - SAML or OIDC connections
Passwords - Traditional password authentication
TOTP - Authenticator app codes
WebAuthn - Biometric or security key authentication

RBAC authorization checks

You can combine session authentication with RBAC permission checks:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/sessions/authenticate \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "authorization_check": {
      "organization_id": "organization-test-...",
      "resource_id": "documents",
      "action": "delete"
    }
  }'

If the member lacks permission, the API returns a 403 error. Otherwise, the response includes which roles satisfied the authorization.

Common operations

Session tokens vs JWTs

Session Tokens

Session JWTs

Authentication factors

RBAC authorization checks

Next steps

Session management guide

RBAC

​Common operations

​Session tokens vs JWTs

Session Tokens

Session JWTs

​Authentication factors

​RBAC authorization checks

​Next steps

Session management guide

RBAC

Common operations

Session tokens vs JWTs

Authentication factors

RBAC authorization checks

Next steps