How to use Member Sessions

Stytch Member Sessions are identified by a session_token or session_jwt that should be stored client-side (usually a browser cookie). The responses from Stytch authenticate endpoints will include a session_token and session_jwt that you can forward to the client and store.

When calling an endpoint like Authenticate Magic Link endpoint, include a session_duration_minutes parameter to create a Session with the specified lifetime. Sessions can be between 5 minutes and 527040 minutes (366 days) long. The response fields will include values for member_session, session_token, and session_jwt.

If left empty, the default length for session_duration_minutes will be set to 60.

On each request, before performing any action that requires authorization, call the Authenticate Session endpoint to ensure that the Session is still valid.

If the Member's Session is still valid, use the member_id to identify the Member and send the session_token or session_jwt to the Member in a session cookie.

If it isn’t valid, clear the session cookie to log the end user out and do not process the request. The Authenticate Session endpoint always returns the session_token or session_jwt for convenience. We recommend following OWASP's guide on cookie storage.

Stytch allows Members to exchange their active Sessions for new Sessions in other Organizations. By calling the Exchange Sessions endpoint, Members can switch between their Organizations without needing to log out and log back in to each Organization individually.

Provide the target organization_id and either the session_token or session_jwt of the active Session to be exchanged.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sessions/exchange \
	-u '{PROJECT_ID}:{SECRET}' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
	}'

To extend a Session’s lifetime, call the Authenticate Session endpoint with the session_duration_minutes parameter. The Session will be set to expire that many minutes from now.

To revoke a Session, call the Revoke Session endpoint with the member_session_id, session_token, session_jwt, or member_id (whichever is mmost convenient).

We recommend showing the end user a list of all their active Sessions so they can revoke any they don’t recognize by IP address and/or User-Agent. To attach values to Sessions, add them to the session_custom_claims parameter in endpoints like the Authenticate Session endpoint and Authenticate Magic Link endpoint.

Create a Session that expires 30 days (43200 minutes) after the initial login.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/magic_links/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"magic_links_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
		"session_duration_minutes": 43200
	}'

curl --request POST \
	--url https://test.stytch.com/b2b/sessions/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
	}'

Everytime a Member's Session is authenticated, extend it for another 30 days (43200 minutes). This means that if the Session continues to be successfully authenticated at least once every 30 days the end user will remain logged in indefinitely, unless the Session is explicitly revoked.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/magic_links/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
		"session_duration_minutes": 43200
	}'

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sessions/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
		"session_duration_minutes": 43200
	}'

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sessions/revoke \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"member_session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509"
	}'

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