Social Authentication

Social login here does not put JWTs in the redirect URL. Your client starts OAuth on the API, the identity provider (IdP) handles consent, and the API returns a short-lived one-time code. Your client then exchanges that code for the same tokens you get from password login.

1. Redirect the user to GET /api/v1/auth/{provider}?redirect=<your allowlisted URL>
2. User signs in with the IdP; the API callback creates or links the user
3. API redirects to your redirect URL with ?code=<exchangeCode> (Redis, ~60s, single use)
4. Your app calls POST /api/v1/auth/exchange with { code } and stores accessToken / refreshToken

// 1) Start OAuth (browser or in-app browser)
GET /api/v1/auth/{provider}?redirect=

// 2) After IdP consent, API redirects your app:
//    <redirect>?code=<one_time_exchange_code>

// 3) Exchange the code for JWTs
POST /api/v1/auth/exchange
{ "code": "" }

// Response (same shape as password login)
{ "user": { ... }, "accessToken": "...", "refreshToken": "..." }

Each provider is off by default. Turn it on in .env (loaded by google-oauth.config.ts, facebook-oauth.config.ts, twitter-oauth.config.ts, github-oauth.config.ts, figma-oauth.config.ts, linkedin-oauth.config.ts, slack-oauth.config.ts, atlassian-oauth.config.ts, gitlab-oauth.config.ts, bitbucket-oauth.config.ts, discord-oauth.config.ts, twitch-oauth.config.ts, steam-openid.config.ts, and reddit-oauth.config.ts under src/config/), create an OAuth app at the IdP, then point the callback URL at this API.

• • Set the provider feature flag to true (e.g. GOOGLE_AUTH_ENABLED, FACEBOOK_AUTH_ENABLED, TWITTER_AUTH_ENABLED, GITHUB_AUTH_ENABLED, FIGMA_AUTH_ENABLED, LINKEDIN_AUTH_ENABLED, SLACK_AUTH_ENABLED, ATLASSIAN_AUTH_ENABLED, GITLAB_AUTH_ENABLED, BITBUCKET_AUTH_ENABLED, DISCORD_AUTH_ENABLED, TWITCH_AUTH_ENABLED, STEAM_AUTH_ENABLED, or REDDIT_AUTH_ENABLED)
• • Fill client/app credentials and CALLBACK_URL (must be the Nest API path, not your SPA)
• • List allowed post-login URLs in the provider REDIRECT_ALLOWLIST (web origin and/or mobile deep link)
• • Optionally set *_OAUTH_DEFAULT_ROLES (comma-separated Role values) for brand-new social users
• • Values are exposed via ConfigService namespaces googleOAuth, facebookOAuth, twitterOAuth, githubOAuth, figmaOAuth, linkedinOAuth, slackOAuth, atlassianOAuth, gitlabOAuth, bitbucketOAuth, discordOAuth, twitchOAuth, steamOpenId, and redditOAuth
• • Follow the provider page below for console steps and env variable names

You only need a start URL and a callback that reads code then calls exchange. Provider pages include copy-paste samples for SPA and React Native / deep links.

• • Web: navigate (or popup) to the start endpoint; on your /auth/callback page, POST the code to /auth/exchange
• • Mobile: open the start URL in an in-app browser; register a deep link in the allowlist; parse code from the return URL and exchange over HTTPS
• • Persist tokens the same way you already do after POST /auth/login
• • Users created only via social login have no local password until you set one

• • Only allowlist redirects you control — open redirects are rejected
• • Treat exchange codes as secrets: one-time, short TTL; never log them
• • POST /auth/exchange is shared across providers; it returns 503 if all social providers are disabled
• • Existing accounts with the same verified email are linked (provider id attached; roles unchanged)

• Auth & JWT — password login, refresh, roles, and guards
• Google OAuth2 setup guide
• Facebook OAuth2 setup guide
• X / Twitter OAuth2 setup guide
• GitHub OAuth2 setup guide
• Figma OAuth2 setup guide
• LinkedIn OpenID Connect setup guide
• Slack OpenID Connect setup guide
• Atlassian OAuth 2.0 (3LO) setup guide
• GitLab OAuth2 setup guide
• Bitbucket OAuth2 setup guide
• Discord OAuth2 setup guide
• Twitch OAuth2 setup guide
• Steam OpenID 2.0 setup guide
• Reddit OAuth2 setup guide
• Amazon Login with Amazon setup guide
• Patreon OAuth2 setup guide
• Dropbox OAuth2 setup guide
• MetaMask SIWE setup guide
• Apple Sign In setup guide