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

# Organization discovery

> Build a Discovery authentication flow for organizations.

## What is discovery?

Discovery refers to a state during authentication where an end user is not yet associated with an organization and is "discovering" the organizations that they are eligible to authenticate into.

***

## What happens

An `intermediate_session_token` is returned in response to any of the Discovery authenticate methods ([example](/api-reference/b2b/frontend-sdks/react/methods/email-magic-links/authenticate-discovery-magic-link)).

A list of [Discovered Organization objects](/api-reference/b2b/api/discovery/discovered-organization-object) is included in the response. This is a list of organizations associated with the member. This can be used to inform subsequent UI to list available organizations for the member to select from.

<Tip>
  If only one organization is associated with the member, you can automatically start a session with that organization by calling `discovery.intermediateSessions.exchange()` with the organization's ID.

  Similarly, if no organizations are associated with the member, you can choose to create a new organization for them to streamline your user experience.
</Tip>

<Check>
  [Stytch UI](/multi-tenant-auth/build-auth/overview) provides configurations, such as `directLoginForSingleMembership`, to handle these scenarios out-of-the-box.
</Check>

### Sample response

```json Response 200 expandable theme={null}
{
    "discovered_organizations": [
        {
            "member_authenticated": false,
            "membership": {
                "details": null,
                "member": {
                    // Full Member object
                },
                "type": "active_member"
            },
            "mfa_required": {
                "member_options": {
                    "mfa_phone_number": "XXXXXXX1234",
                    "totp_registration_id": ""
                },
                "secondary_auth_initiated": null
            },
            "organization": {
                // Full Organization object (fields omitted for brevity)
                ...
                "organization_id": "organization-...",
                "organization_logo_url": "",
                "organization_name": "Example Organization One",
                "organization_slug": "example-organization-one",
            },
            "primary_required": null
        },
        {
            "member_authenticated": true,
            "membership": {
                "details": null,
                "member": {
                    // Full Member object
                },
                "type": "pending_member"
            },
            "mfa_required": null,
            "organization": {
                // Full Organization object (fields omitted for brevity)
                ...
                "organization_id": "organization-...",
                "organization_logo_url": "",
                "organization_name": "Example Organization Two",
                "organization_slug": "example-organization-two",
            },
            "primary_required": null
        },
    ],
    "email_address": "example@stytch.com",
    "intermediate_session_token": "Is9gF...",
    "request_id": "request-id-...",
    "status_code": 200
}
```

***

## Select or create an organization

At this point, you can have users select an organization to start a session with or allow them to create a new organization using either method.

<Card title="discovery.intermediateSessions.exchange()" icon="code" href="/api-reference/b2b/frontend-sdks/react/methods/discovery/exchange-intermediate-session">
  Start a session with a selected organization.
</Card>

<Card title="discovery.organizations.create()" icon="code" href="/api-reference/b2b/frontend-sdks/react/methods/discovery/create-organization-via-discovery">
  Allow users to create a new organization.
</Card>

The `intermediate_session_token` is automatically saved in browser cookies by the SDK and isn't required to be explicitly passed into these methods.

<Warning>To allow organization creation via the frontend, the [Create Organizations setting](https://stytch.com/dashboard/sdk-configuration) must be enabled for your project.</Warning>

### Example

```javascript wrap theme={null}
export const exchangeDiscoveryIntermediateSessionToken = (organization_id) => {
    stytch.discovery.intermediateSessions.exchange({
        organization_id,
        session_duration_minutes: DESIRED_SESSION_LENGTH,
    });
}

export const createOrganization = (organization_name, organization_slug) => {
    stytch.discovery.organizations.create({
        organization_name,
        organization_slug,
        session_duration_minutes: DESIRED_SESSION_LENGTH,
    });
}
```

***

## Next steps

If the end user selects an organization where `member_authenticated` is `false`, you will need to trigger additional MFA or step-up authentication steps based on the authentication requirements of the selected organization.
Instead of calling the endpoints above, you can proceed directly to step-up authentication (if the `primary_required` value is non-null) or MFA (if the `mfa_required` value is non-null).

<Columns cols={2}>
  <Card title="Step-up authentication" href="./step-up" icon="arrow-up-right">
    Adding step-up authentication.
  </Card>

  <Card title="Multi-factor authentication (MFA)" href="./mfa" icon="arrow-up-right">
    Handling multi-factor authentication.
  </Card>
</Columns>