Social Login

The SDK supports social login with Google, Facebook, and Apple.

The flow:

1. Your frontend uses the official provider SDK to authenticate the user.
2. The provider returns a short-lived token.
3. You pass this token to the Platform SDK to exchange it for a platform session.

Provider token types

Provider	Token to pass	Notes
Google	id_token (Google Identity Services credential)	JWT; backend verifies with Google
Facebook	access token	Backend verifies via Facebook's debug_token endpoint
Apple	id_token	Must be obtained with a nonce; backend verifies the nonce claim

// Google example
const googleResponse = await google.accounts.id.getToken();
const idToken = googleResponse.credential;

// Exchange it for a platform session
await sdk.auth.loginWithSocial('GOOGLE', idToken);

type SocialProvider = 'GOOGLE' | 'FACEBOOK' | 'APPLE';
// loginWithSocial(provider: SocialProvider, token: string): Promise<User>

Account linking policy

When a social identity's email matches an existing account's email:

GIVEN a social identity whose email matches an existing account
WHEN both the provider email AND the existing account email are verified
THEN the social identity is LINKED to the existing account
     and the user is logged in (no duplicate account is created).

GIVEN a social identity whose email matches an existing account
WHEN either email is NOT verified
THEN loginWithSocial throws SocialAccountExistsError (AUTH_SOCIAL_ACCOUNT_EXISTS)
     and the user is told to log in with their password and link the provider
     from account settings.

Matching on provider + providerUserId always logs into the existing linked account directly. Unknown identities with no email collision create a new linked account; duplicates are never created for the same identity.

Sandbox: social tokens are find-or-create by identity; pass them as PROVIDER:externalId. The seeded identity GOOGLE:google_lia_123 logs in as LiaSocial; unknown identities create a new linked account. See Environments & Sandbox Data.