Documentation Index Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
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 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 validatesession_duration_minutes: (Optional) Extend session lifetime by this many minutessession_custom_claims: (Optional) Custom claims to add to the session JWTauthorization_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 revokesession_jwt: Alternative - the session JWT to revokemember_session_id: Alternative - the session ID to revokemember_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 authenticationOAuth - Social login (Google, Microsoft, etc.)OTP - One-time passcodes via email or SMSSSO - SAML or OIDC connectionsPasswords - Traditional password authenticationTOTP - Authenticator app codesWebAuthn - 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.
Next steps
Session management guide Comprehensive session documentation
RBAC Implement role-based access control with sessions
