Skip to main content

​
API resources

API Reference

Use the OAuth API to start an OAuth flow.

Frontend SDKs

Use the OAuth SDKs to start an OAuth flow.

Stytch UI

Use Stytch’s pre-built UI components to seamlessly add OAuth to your login flow.

​
Authentication flows

OAuth, otherwise known as Social Login or Social SSO, is an easy way for end users to sign-up and login to your application through their authenticated identity on common OAuth providers, such as Google or Microsoft. Visually, the OAuth flow looks like this:

​
Discovery vs. Organization-specific login

Stytch’s Multi-Tenant Authentication product supports two different OAuth authentication flows:

Organization-specific authentication

Used when you already know the that the end user is trying to log into.

Discovery authentication

Used for self-serve Organization creation or login prior to knowing the Organization context.
Both flows support OAuth, allowing end users to accept pending invites or by email domain, and finish with the end user authenticated in a specific Organization. However, involves one additional step to surface the end user’s “discovered organizations” that they are eligible to login to and also allows self-serve organization creation.

​
Key differences

DiscoveryOrganization-Specific
OAuth Start Initiated Withpublic_tokenpublic_token and organization_id OR slug
Redirect URL Used for CallbackDiscoveryLogin or Sign-up
Stytch Token Typediscovery_oauthoauth
Authenticate Methodoauth.discovery.authenticate()oauth.authenticate()
Access and Refresh TokenRetrieve via Get Access Token APIs after organization selectionReturned in oauth.authenticate() response, or can retrieve via Get Access Token APIs

​
Just-in-Time provisioning

​
Enabling JIT provisioning for OAuth tenants

If your project is configured to use Slack, HubSpot, or GitHub as identity providers for OAuth, organizations can enable Just-in-Time (JIT) Provisioning of end users based on tenant ID. A tenant ID is a unique identifier for a subgroup within one of these OAuth providers:
  • Slack’s Workspace ID
  • HubSpot’s Hub ID
  • GitHub’s organization ID
An end user who completes a Discovery OAuth flow where the tenant ID of the provider they authenticated with matches a tenant ID in an organization’s Allowed Tenants list will have that organization surfaced in their Discovery response and will subsequently be allowed to authenticate into that organization.
See instructions for finding your provider’s tenant ID in our JIT Provisioning guide.
If the tenant ID does not match any of the organization’s Allowed Tenants, the end user will have to undergo further authentication of their email (i.e. a step-up) before being permitted to perform certain actions in Stytch, such as JIT provisioning by email domain or creating a new organization.

​
Understanding step-up requirements

If the tenant ID of the provider matches a tenant ID in the organization’s Allowed Tenants, the end user will be fully authenticated after completing an OAuth flow. If the tenant ID of the provider does not match any of the Allowed Tenants, but an end user is still eligible to join the organization via their email domain, an end user wishing to authenticate using Slack, HubSpot, or GitHub as identity providers are required to do a “step-up” form of primary authentication (such as Email Magic Links, Email OTP, Google OAuth, or Microsoft OAuth) before being able to receive a full session and fully authenticate as a . Additionally, Google and Microsoft are non-authoritative about the user’s active ownership of their email address for some account types, and in these cases the user must also complete step-up authentication (such as Email Magic Links or Email OTP) before being granted a full session.
Active Members (Members that have been pre-created in an Organization or have previously completed step-up authentication) and Members whose tenant ID match the Organization’s Allowed Tenants are allowed to sign-in via these providers without undergoing any step-up requirements.
When an end user authenticates via OAuth and opts to JIT Provision into an organization they are eligible to join based on the email domain returned, fields are provided in the OAuth authenticate response that inform the developer whether an end user needs to step-up and how to satisfy the step-up requirement:
  • member_authenticated: will be false to indicate that the end user requires step-up authentication.
  • primary_required: details actions that the Member must take in order to meet the step-up requirement for the Organization in question.
  • intermediate_session_token: this will be populated with the same token the end user received when completing OAuth authentication.