Skip to main content

​
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.
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:

​
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:
​
member_authenticated
boolean
Value will be false.
​
primary_required
object | null
Value will be non-null and include which forms of primary authentication are required by the organization.
​
mfa_required
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.

​
Sample response

An OAuth authenticate response where primary step-up authentication is required:
Response 200
{
    "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.
The intermediate_session_token must be included in the subsequent authenticate request to complete step-up.
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.

​
Additional resources

Understanding step-up requirements in OAuth