Social Login

Authenticate user via social login provider (GitHub/Google/Apple/Microsoft).

Endpoint

POST /api/v1/auth/oauth/login

Headers

Header	Required	Description
Content-Type	Yes	application/json
x-device-fingerprint	No	JSON string with device fingerprinting data

Request Body

{
  "provider": "github",
  "code": "authorization_code_from_provider"
}

Parameters

Field	Type	Required	Description
provider	string	Yes	OAuth provider: "github", "google", "apple", "microsoft"
code	string	Yes	Authorization code from OAuth provider

Validations

• Provider validation
• Authorization code format validation
• Code expiration check

Response

Success (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": 123,
    "email": "user@example.com",
    "display_name": "John Doe",
    "is_new_user": false,
    "provider": "github",
    "message": "GitHub login successful"
  },
  "message": "GitHub login successful"
}

Error Codes

Status	Code	Description
400	SOCIAL_LOGIN_FAILED	Authentication failed
400	INVALID_PROVIDER	Invalid provider
422	VALIDATION_ERROR	Request validation failed

Data Flow

1. Code Exchange

   • Exchange authorization code for access token
   • Request to OAuth provider
   • Validate provider response

2. User Information Retrieval

   • Get user profile from provider
   • Extract email, name, avatar
   • Validate provider response

3. User Lookup/Creation

   • Check if user exists by provider ID or email
   • If exists:
     • Link SSO session
     • Update last login
   • If new:
     • Create user account
     • Create organization
     • Create workspace

4. SSO Session Creation

   • Create SsoSession record
   • Link to AuthProvider
   • Store provider access token (encrypted)

5. Token Generation

   • Generate OAuth2 access token
   • Generate refresh token
   • MFA is bypassed (provider authenticates user)

6. Session Creation

   • Create session with IP and user agent
   • Device fingerprinting

7. Audit Logging

   • Log social login event
   • Record provider used

Features

• Exchanges authorization code for access token
• Retrieves user information from OAuth provider
• Creates or links user account
• Returns OAuth2 tokens (access + refresh)
• Bypasses MFA (social providers already authenticate the user)
• Audit logging
• Session management

Example

curl -X POST https://api.rivergen.com/api/v1/auth/oauth/login \
  -H "Content-Type: application/json" \
  -H "x-device-fingerprint: {\"screen\":\"1920x1080\"}" \
  -d '{
    "provider": "github",
    "code": "authorization_code_abc123"
  }'

Related Endpoints

• Get OAuth URL - Get authorization URL
• OAuth Callback - Handle provider callback
• Social Accounts - View connected accounts