> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Social Login

> Authenticate via Google or Apple OAuth tokens.

# Social Login

Allows users to sign in or register with third-party identity providers (Google ID Tokens and Apple Identity Tokens).

***

## Social Login Endpoint

If the user account does not yet exist, a partial registration session is initiated, prompting the client to call `/api/v2/auth/setup-account` if extra profile fields are needed.

### Endpoint

```http theme={null}
POST /api/v2/auth/login-with-social
```

### Request Body

| Field       | Type     | Required | Description                                        |
| :---------- | :------- | :------- | :------------------------------------------------- |
| `email`     | `string` | **Yes**  | Email returned by OAuth provider                   |
| `provider`  | `string` | **Yes**  | Identity provider: `"google"` or `"apple"`         |
| `token`     | `string` | No       | ID token / credential from Google or Apple Sign-In |
| `firstName` | `string` | No       | First name from provider                           |
| `lastName`  | `string` | No       | Last name from provider                            |
| `avatarUrl` | `string` | No       | Profile photo URL                                  |

```json theme={null}
{
  "email": "johndoe@gmail.com",
  "provider": "google",
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "firstName": "John",
  "lastName": "Doe"
}
```

### Response (200 OK - Existing User)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "johndoe@gmail.com",
    "username": "johndoe_web3",
    "role": "USER",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  },
  "message": "Social authentication successful"
}
```

### Response (200 OK - New User Onboarding Required)

```json theme={null}
{
  "success": true,
  "data": {
    "isNewUser": true,
    "email": "johndoe@gmail.com",
    "provider": "google",
    "suggestedUsername": "johndoe"
  },
  "message": "Please finalize your profile details"
}
```