OAuth Callback

Handle OAuth callback from provider. Automatically determines login or signup.

Endpoint

GET /api/v1/auth/oauth/{provider}/callback

Headers

None required (public endpoint)

Path Parameters

Parameter	Type	Required	Description
provider	string	Yes	OAuth provider: "github", "google", "apple", "microsoft"

Query Parameters

Parameter	Type	Required	Description
code	string	Yes	Authorization code from OAuth provider
state	string	No	State parameter for CSRF protection
error	string	No	Error code if authorization failed
error_description	string	No	Error description if authorization failed

Validations

• Provider validation
• Authorization code validation
• State parameter validation (CSRF protection)
• Error handling from provider

Response

Success - Existing User (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"
}

Success - New User (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": 124,
    "email": "newuser@example.com",
    "display_name": "Jane Smith",
    "is_new_user": true,
    "provider": "github",
    "message": "GitHub signup successful"
  },
  "message": "GitHub signup successful"
}

Error Codes

Status	Code	Description
400	OAUTH_AUTHORIZATION_FAILED	OAuth authorization failed
400	MISSING_AUTHORIZATION_CODE	Authorization code is required
400	INVALID_PROVIDER	Invalid provider

Data Flow

1. Error Handling

   • Check for OAuth errors from provider
   • Return error if authorization failed

2. Code Validation

   • Verify authorization code is present
   • Validate code format

3. Code Exchange

   • Exchange code for access token
   • Get user profile from provider

4. User Detection

   • Check if user exists (by provider ID or email)
   • If user exists:
     • Run login flow
     • Return SocialLoginResponse
   • If new user:
     • Run signup flow
     • Return SocialSignupResponse

5. Account Operations

   • Link SSO session (if existing user)
   • Create user account (if new user)
   • Create organization/workspace (if new user)

6. Token Generation

   • Generate OAuth2 tokens
   • Bypass MFA

7. Response

   • Return appropriate response type
   • Include is_new_user flag

Features

• Automatically determines login or signup
• If user exists: Runs login functionality (no MFA)
• If user doesn't exist: Runs signup functionality (no MFA)
• Handles OAuth errors gracefully
• CSRF protection via state parameter
• Returns appropriate response type

Example

https://api.rivergen.com/api/v1/auth/oauth/github/callback?code=abc123&state=csrf_token

Related Endpoints

• Get OAuth URL - Get authorization URL
• Social Login - Explicit login flow
• Social Signup - Explicit signup flow