Discovery overview

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

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": {}
      }
    }
  ]
}

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

Join organization or create new

The member can now choose to join an existing organization or create a new one:

Join Existing Organization
Create New Organization

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.

Create a new organization using the Create Organization via Discovery endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/discovery/organizations/create \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "intermediate_session_token": "intermediate_session_token_...",
    "organization_name": "New Company",
    "organization_slug": "new-company",
    "session_duration_minutes": 60
  }'

Creates a new organization with the member as the first member and returns a full session.

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

Discovery flow

Discovery

Organization-specific

Learn more

Core flows

Discovered Organization object

​Discovery flow

​Discovery vs Organization-specific login

Discovery

Organization-specific

​Learn more

Core flows

Discovered Organization object

Discovery flow

Discovery vs Organization-specific login

Learn more