Skip to main content

​
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). A list of Discovered Organization objects 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.
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.
Stytch UI provides configurations, such as directLoginForSingleMembership, to handle these scenarios out-of-the-box.

​
Sample response

Response 200
{
    "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.

discovery.intermediateSessions.exchange()

Start a session with a selected organization.

discovery.organizations.create()

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.
To allow organization creation via the frontend, the Create Organizations setting must be enabled for your project.

​
Example

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

Step-up authentication

Adding step-up authentication.

Multi-factor authentication (MFA)

Handling multi-factor authentication.