Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.prelude.so/llms.txt

Use this file to discover all available pages before exploring further.

Social login allows users to authenticate with their existing accounts from providers like Google, Apple, Microsoft, GitHub, Okta, and Facebook.

​
Prerequisites

Before you start, make sure you have:
  • A Prelude account with access to the Session API
  • An Application ID (appID) — see Applications
  • Your Management API key for backend calls
  • OAuth credentials from the provider you want to configure (client ID, client secret, etc.)

​
Supported providers

ProviderIdentifier
Googlegoogle
Appleapple
Microsoftmicrosoft
GitHubgithub
Oktaokta
Facebookfacebook

​
Configuration options

All providers share the following options:
FieldTypeDescription
client_idstringOAuth client ID from the provider.
client_secretstringOAuth client secret from the provider.
enabledbooleanSet to true to enable the provider.
options.use_email_as_identifierbooleanWhen true, creates an email identifier for new OAuth users. Only applied when the email is verified — either by the provider, or via the verify_email OTP flow.
options.allow_email_account_mergebooleanWhen true, allows merging accounts that share the same verified email address.
options.verify_emailbooleanWhen true, falls back to an email OTP challenge when the provider returns an unverified email. See Verify email via OTP below. Requires use_email_as_identifier=true and at least one email OTP login config; both are enforced at write time.
Some providers require additional configuration — see the provider-specific guides below.

​
Email verification trust model

use_email_as_identifier and allow_email_account_merge both depend on whether the provider vouches that the email belongs to the signed-in user. Session uses provider-specific signals:
ProviderVerification signalNotes
Googleemail_verified claim in ID tokenVerified by default.
Appleemail_verified claim in ID tokenVerified by default.
Microsoftxms_edov optional claimNot verified by default. Customers must enable the xms_edov optional claim in Azure Token Configuration — otherwise the email is treated as unverified and auto-merge is disabled. See the Microsoft guide for setup steps and background on the nOAuth vulnerability this prevents.
GitHubPrimary + verified email from the /user/emails APIVerified by default.
Oktaemail_verified claim in ID tokenDepends on your Okta tenant configuration.
FacebookReturned email from the Graph APIVerified by default.
When a provider surfaces an email as unverified, Session will not store it as an identifier and will not auto-merge it into an existing account. If allow_email_account_merge is enabled and an unverified email collides with an existing Session user, the flow is rejected with an email_in_use error instead of silently linking the accounts.

​
Verify email via OTP

Enable verify_email on a provider when you want users to keep signing in even if the IdP returns the email as unverified. Instead of rejecting the flow or creating an unlinked account, Session sends an email OTP to the address surfaced by the IdP and links the OAuth identifier only after the user proves ownership. The flow:
  1. The user signs in with the OAuth provider.
  2. The IdP returns an email but does not vouch for it (e.g. Microsoft without xms_edov, or a custom Okta tenant).
  3. Session redirects back to your app with challenge_token=…&status=otp_required instead of finalizing the login.
  4. The Web SDK’s finalizeOAuthLogin returns { status: "otp_required", challengeId, email } so your app can route to its OTP screen and call checkOTP with the code the user entered.
  5. On a successful OTP, Session attaches the OAuth identifier to (or creates) the user that owns the email and finalizes the login automatically.
Preconditions enforced when you save the OAuth config:
  • use_email_as_identifier must be true. Verifying an email that will never be persisted as an identifier serves no purpose.
  • The application must have at least one email OTP login config. Removing the last email OTP login config while any provider still has verify_email=true is rejected.
If verify_email is true but use_email_as_identifier is later flipped off, the OTP step is skipped at runtime and the account is created with only the OAuth identifier — the existing config keeps loading instead of breaking, but the OAuth-link flow is effectively disabled until both flags are aligned. When the email already belongs to another account and allow_email_account_merge is false, Session rejects with email_in_use before sending the OTP so the user does not get sent through a screen for a flow that would dead-end.

​
Provider guides

Google

Configure Google OAuth for your application.

Apple

Configure Apple OAuth for your application.

Microsoft

Configure Microsoft OAuth for your application.

GitHub

Configure GitHub OAuth for your application.

Okta

Configure Okta OAuth for your application.

Facebook

Configure Facebook OAuth for your application.