B2B Saas Authentication

/

API reference

/

Session management

/

Exchange Session

Exchange Session

POSThttps://test.stytch.com/v1/b2b/sessions/exchange

Use this endpoint to exchange a Member's existing session for another session in a different Organization. This can be used to accept an invite, but not to create a new member via domain matching.

To create a new member via domain matching, use the Exchange Intermediate Session flow instead.

Only Email Magic Link, OAuth, and SMS OTP factors can be transferred between sessions. Other authentication factors, such as password factors, will not be transferred to the new session. Any OAuth Tokens owned by the Member will not be transferred to the new Organization. SMS OTP factors can be used to fulfill MFA requirements for the target Organization if both the original and target Member have the same phone number and the phone number is verified for both Members. HubSpot and Slack OAuth registrations will not be transferred between sessions. Instead, you will receive a corresponding factor with type "oauth_exchange_slack" or "oauth_exchange_hubspot"

If the Member is required to complete MFA to log in to the Organization, the returned value of member_authenticated will be false, and an intermediate_session_token will be returned. The intermediate_session_token can be passed into the OTP SMS Authenticate endpoint to complete the MFA step and acquire a full member session. The intermediate_session_token can also be used with the Exchange Intermediate Session endpoint or the Create Organization via Discovery endpoint to join a different Organization or create a new one. The session_duration_minutes and session_custom_claims parameters will be ignored.


Body parameters


organization_id*string

session_tokenstring

session_jwtstring

session_duration_minutesint

session_custom_claimsmap<string, any>

localestring

Response fields


request_idstring

status_codeint

member_idstring

session_tokenstring

session_jwtstring

intermediate_session_tokenstring

member_authenticatedboolean

mfa_requiredobject

member_sessionobject

memberobject

organizationobject
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"
  }'

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_jwt": "example_jwt",
	"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
	"intermediate_session_token": "",
	"member_authenticated": true,
	"mfa_required": null,
	"member_session": {...},
	"member": {...},
	"organization": {...}
}

Common Error Types