> ## 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.

# Discovery overview

> Help members find and join organizations they have access to using the Stytch API

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

<Steps>
  <Step title="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:**

    ```bash theme={null}
    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:

    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "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": {}
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="List discovered organizations">
    Get all organizations the member can access using the [List Organizations](/docs/api-reference/b2b/api/discovery/list-organizations) endpoint:

    ```bash theme={null}
    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
  </Step>

  <Step title="Join organization or create new">
    The member can now choose to join an existing organization or create a new one:

    <Tabs>
      <Tab title="Join Existing Organization" icon="building">
        Exchange the intermediate session for a full member session using the [Exchange Intermediate Session](/docs/api-reference/b2b/api/discovery/exchange-intermediate-session) endpoint:

        ```bash theme={null}
        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:**

        ```json theme={null}
        {
          "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.
      </Tab>

      <Tab title="Create New Organization" icon="plus">
        Create a new organization using the [Create Organization via Discovery](/docs/api-reference/b2b/api/discovery/create-organization-via-discovery) endpoint:

        ```bash theme={null}
        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.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Discovery vs Organization-specific login

<CardGroup cols={2}>
  <Card title="Discovery" icon="scan-search">
    * Member authenticates without specifying organization
    * Sees all organizations they can access
    * Can create new organizations
    * Uses `discovery_` auth endpoints
    * Returns `intermediate_session_token`
  </Card>

  <Card title="Organization-specific" icon="building">
    * 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`
  </Card>
</CardGroup>

## Learn more

<CardGroup cols={2}>
  <Card title="Core flows" icon="book" href="/docs/multi-tenant-auth/auth-flows">
    Learn about Discovery and organization switching
  </Card>

  <Card title="Discovered Organization object" icon="search-check" href="/docs/api-reference/b2b/api/discovery/discovered-organization-object">
    Object reference for discovered organizations
  </Card>
</CardGroup>