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

# Step-up authentication

> Sessions during step-up authentication flows.

## What is step-up authentication?

Step-up authentication is a specific type of multi-factor authentication where the application requests additional identification information to verify a user's identity.

<Accordion title="Example: Primary step-up during OAuth discovery">
  When a user is eligible to join an organization via their email domain but the OAuth provider's tenant ID does not match an allowed tenant,
  step-up primary authentication is required before a session is granted.

  For example, a user may sign in with GitHub OAuth and then complete step-up primary authentication using Google OAuth or an email OTP.

  **Also see:**

  * [Understanding step-up requirements in OAuth discovery](/multi-tenant-auth/authentication/oauth/overview#understanding-step-up-requirements)
</Accordion>

***

## What happens

If a user is required to an additional form of primary authentication, an `intermediate_session_token` is returned instead of a `session_token` in response to the initial authentication request.

The following values will also be set in the authentication response:

<ResponseField name="member_authenticated" type="boolean">
  Value will be `false`.
</ResponseField>

<ResponseField name="primary_required" type="object | null">
  Value will be non-null and include which forms of primary authentication are required by the organization.

  <Expandable title="properties">
    <ResponseField name="allowed_auth_methods" type="array[string]">
      Details the list of auth methods that the member can complete to fulfill the primary authentication requirements of the organization. The member must complete at least one of the options presented.

      * For example, a value of `[magic_link]` indicates that the Member must also complete a magic link authentication step.
      * The `intermediate_session_token` must be passed into that primary authentication step.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="mfa_required" type="object | null">
  Value may be non-null if the member also needs to complete MFA for the organization. The member should complete the primary step-up authentication step first before proceeding to the MFA step.
</ResponseField>

### Sample response

An OAuth authenticate response where primary step-up authentication is required:

```json Response 200 expandable theme={null}
{
    "intermediate_session_token": "fTwWh...",
    "member": {
        // Full Member object
    },
    "member_authenticated": false,
    "member_id": "member-...",
    "member_session": null,
    "mfa_required": null,
    "organization": {
        // Full Organization object
    },
    "organization_id": "organization-...",
    "primary_required": {
        "allowed_auth_methods": [
            "sso",
            "microsoft_oauth",
            "email_otp",
            "magic_link",
            "google_oauth"
        ]
    },
    "provider_subject": "U08...",
    "provider_type": "Slack",
    "provider_values": {
        "access_token": "x2f...",
        "expires_at": "2024-12-10T20:11:53Z",
        "id_token": null,
        "refresh_token": null,
        "scopes": [
            "users:read",
            "users:read.email"
        ]
    },
    "request_id": "request-id-...",
    "reset_sessions": false,
    "session_jwt": "",
    "session_token": "",
    "status_code": 200
}
```

***

## Next steps

You will need to prompt the user to complete one of the authentication methods present in the `primary_required` array before they can be fully authenticated and granted a full member session.

<Warning>
  The `intermediate_session_token` must be included in the subsequent authenticate request to complete step-up.
</Warning>

<Note>
  The methods specified under `primary_required.allowed_auth_methods` can be used for step-up even if they're not enabled as an authentication method for the organization.

  For example, email magic links can be used for step-up authentication even if magic links isn't enabled as a primary authentication method on the organization.
</Note>

### Additional resources

<Columns cols={2}>
  <Card title="Understanding step-up requirements in OAuth" href="/multi-tenant-auth/authentication/oauth/overview#understanding-step-up-requirements" icon="arrow-up-right" />
</Columns>