Skip to main content
Discovery allows members to authenticate and see all organizations they can access - whether they’re existing members, have pending invites, or are eligible to join via email domain or SSO configuration. Members can then select an organization to authenticate into or create a new one.

​
Discovery flow

1

Authenticate with discovery

Use any discovery authentication method (Email Magic Link, Email OTP, OAuth, or Password) to get an intermediate_session_token:Example with Email Magic Link:
curl --request POST \
  --url https://test.stytch.com/v1/b2b/magic_links/email/discovery/send \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "email_address": "user@example.com"
  }'
After the member clicks the magic link, extract the discovery_magic_links_token from the callback URL and authenticate:
curl --request POST \
  --url https://test.stytch.com/v1/b2b/magic_links/email/discovery/authenticate \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "discovery_magic_links_token": "token-from-email-..."
  }'
Response:
{
  "status_code": 200,
  "intermediate_session_token": "intermediate_session_token_...",
  "email_address": "user@example.com",
  "discovered_organizations": [
    {
      "organization": {
        "organization_id": "organization-test-...",
        "organization_name": "Acme Corp",
        "organization_slug": "acme-corp"
      },
      "membership": {
        "type": "active_member",
        "details": {}
      }
    }
  ]
}
2

List discovered organizations

Get all organizations the member can access using the List Organizations endpoint:
curl --request POST \
  --url https://test.stytch.com/v1/b2b/discovery/organizations \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "intermediate_session_token": "intermediate_session_token_..."
  }'
Response includes organizations where the member:
  • active_member - Already a member
  • pending_member - Has a pending invite
  • invited_member - Has been invited
  • eligible_to_join_by_email_domain - Email domain matches organization’s allowed domains
  • eligible_to_join_by_oauth_tenant - OAuth tenant matches organization’s allowed tenants
3

Join organization or create new

The member can now choose to join an existing organization or create a new one:
Exchange the intermediate session for a full member session using the Exchange Intermediate Session endpoint:
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": "intermediate_session_token_...",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "session_duration_minutes": 60
  }'
Response:
{
  "status_code": 200,
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "session_jwt": "eyJhbGc...",
  "member_authenticated": true
}
If the organization requires MFA, the response will have member_authenticated: false and include a new intermediate_session_token to complete the MFA challenge.

​
Discovery vs Organization-specific login

Discovery

  • Member authenticates without specifying organization
  • Sees all organizations they can access
  • Can create new organizations
  • Uses discovery_ auth endpoints
  • Returns intermediate_session_token

Organization-specific

  • Member authenticates to a specific organization
  • Typically uses organization slug in URL
  • Direct login to known organization
  • Uses standard auth endpoints with organization_id
  • Returns full session_token

​
Learn more

Core flows

Learn about Discovery and organization switching

Discovered Organization object

Object reference for discovered organizations