Flowless Docs

Appearance

OAuth Callback Handler​

GET
/auth/social/{provider}/callback

⚠️ BETA FEATURE - Handle OAuth callback from social provider. This endpoint is called automatically by the OAuth provider after user authentication.

Web redirect behavior:

  • Full session (no 2FA): Redirects to {FRONTEND_URL}/login?social_login=success&provider={provider}. Session token is delivered via HTTP-only cookie — the frontend calls GET /auth/session/current to resolve it.
  • 2FA required: Redirects to {FRONTEND_URL}/login?social_login=success&requires_2fa=true&session_id={partial_session_id}&provider={provider}. The partial session_id is always included in the URL for the 2FA case, even when callback_mode=cookie is configured. This is necessary because Safari ITP and privacy-focused browsers block cookies set during cross-origin OAuth redirect chains, making cookie-only delivery unreliable for the 2FA step. The partial session expires in 5 minutes and still requires a valid OTP code.

Parameters​

Path Parameters

provider*
Type
string
Required
Valid values
"google""github""facebook""apple""discord""microsoft"

Query Parameters

code*

Authorization code from OAuth provider

Type
string
Required
format

Response format (json for API clients, omit for web redirect)

Type
string
Valid values
"json"

Responses​

Authentication successful (API format)

application/json
JSON
{
  
"success": true,
  
"user": {
  
  
"id": "usr_abc123",
  
  
"email": "user@example.com",
  
  
"name": "John",
  
  
"last_name": "Doe",
  
  
"user_name": "johndoe",
  
  
"user_type": "customer",
  
  
"picture": "https://storage.pubflow.com/users/usr_abc123/picture.jpg",
  
  
"phone": "+1234567890",
  
  
"is_verified": true,
  
  
"two_factor": false,
  
  
"created_at": "2025-12-07T10:00:00Z",
  
  
"updated_at": "2025-12-07T10:00:00Z"
  
},
  
"sessionId": "ses_xyz789",
  
"expiresAt": "string",
  
"loginType": "social_auth",
  
"provider": "google"
}

Playground​

Server
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI