> ## 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](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/email-magic-links/authenticate-discovery-magic-link.md)).

A list of [Discovered Organization objects](https://stytch.com/docs/api-reference/b2b/api/discovery/discovered-organization-object.md) 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]
>
> [Stytch UI](https://stytch.com/docs/multi-tenant-auth/build-auth/overview.md) provides configurations, such as `directLoginForSingleMembership`, to handle these scenarios out-of-the-box.

### 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] [discovery.intermediateSessions.exchange()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/discovery/exchange-intermediate-session.md)
>
> Start a session with a selected organization.

> [card] [discovery.organizations.create()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/discovery/create-organization-via-discovery.md)
>
> Allow users to create a new organization.

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.

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

> [card] [Step-up authentication](https://stytch.com/docs/multi-tenant-auth/manage-sessions/intermediate-sessions/step-up.md)
>
> Adding step-up authentication.

> [card] [Multi-factor authentication (MFA)](https://stytch.com/docs/multi-tenant-auth/manage-sessions/intermediate-sessions/mfa.md)
>
> Handling multi-factor authentication.
