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

**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:**

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

**2. List discovered organizations**

Get all organizations the member can access using the [List Organizations](https://stytch.com/docs/api-reference/b2b/api/discovery/list-organizations.md) 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

**3. Join organization or create new**

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

> [tab] Join Existing Organization
>
> Exchange the intermediate session for a full member session using the [Exchange Intermediate Session](https://stytch.com/docs/api-reference/b2b/api/discovery/exchange-intermediate-session.md) 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] Create New Organization
>
> Create a new organization using the [Create Organization via Discovery](https://stytch.com/docs/api-reference/b2b/api/discovery/create-organization-via-discovery.md) 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.

## Discovery vs Organization-specific login

> [card] Discovery
>
> * Member authenticates without specifying organization
> * Sees all organizations they can access
> * Can create new organizations
> * Uses `discovery_` auth endpoints
> * Returns `intermediate_session_token`

> [card] 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

> [card] [Core flows](https://stytch.com/docs/multi-tenant-auth/auth-flows)
>
> Learn about Discovery and organization switching

> [card] [Discovered Organization object](https://stytch.com/docs/api-reference/b2b/api/discovery/discovered-organization-object.md)
>
> Object reference for discovered organizations
