Social Authentication

This section covers social authentication operations available in the GraphQL Main API. The API supports various social login providers including Facebook, Google, etc.

Note: The Telegram provider in social authentication is currently marked as NOT_IMPLEMENTED in the codebase.

Mutations

registerWithSocial

Initiate the registration process using a social account.

mutation RegisterWithSocial($input: RegisterWithSocialInput!) {
  registerWithSocial(input: $input) {
    status
    url
    state
    errorMessage
  }
}

Input:

input RegisterWithSocialInput {
  type: AuthSocialType!              // The social provider type (GOOGLE, FACEBOOK, etc.)
  redirectPath: String!              // The path where the user will be redirected after authentication
  agreedToTerms: Boolean!            // Confirmation that user has agreed to terms of service
  receiveMarketingOffers: Boolean!   // User's preference for marketing communications
  fingerprint: String                // Optional device fingerprint for additional security
  referrerUserId: String             // Optional ID of the referring user
  referrerUsername: String           // Optional username of the referring user
  promoCode: String                  // Optional promotional code
}

Returns:

type GenerateSocialAuthUrlResponse {
  status: ResponseStatus!   // SUCCESS or ERROR
  url: String               // URL to redirect the user to the social provider's auth page
  state: String             // State parameter for CSRF protection
  errorMessage: String      // Error message if status is ERROR
}

Example Input:

mutation {
  registerWithSocial(
    input: {
      type: GOOGLE
      redirectPath: "/auth/callback"
      agreedToTerms: true
      receiveMarketingOffers: false
      fingerprint: "device-fingerprint-123"
    }
  ) {
    status
    url
    state
    errorMessage
  }
}

Example Output:

{
  "data": {
    "registerWithSocial": {
      "status": "SUCCESS",
      "url": "https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...",
      "state": "random_state_string_for_verification",
      "errorMessage": null
    }
  }
}

The AuthSocialType enum includes values like FACEBOOK, GOOGLE, etc.

loginWithSocial

Initiate the login process using a social account.

mutation LoginWithSocial($input: LoginWithSocialInput!) {
  loginWithSocial(input: $input) {
    status
    url
    state
    errorMessage
  }
}

Input:

input LoginWithSocialInput {
  type: AuthSocialType!     // The social provider type (GOOGLE, FACEBOOK, etc.)
  redirectPath: String!     // The path where the user will be redirected after authentication
  fingerprint: String       // Optional device fingerprint for additional security
}

Returns:

type GenerateSocialAuthUrlResponse {
  status: ResponseStatus!   // SUCCESS or ERROR
  url: String               // URL to redirect the user to the social provider's auth page
  state: String             // State parameter for CSRF protection
  errorMessage: String      // Error message if status is ERROR
}

Example Input:

mutation {
  loginWithSocial(
    input: {
      type: FACEBOOK
      redirectPath: "/auth/callback"
      fingerprint: "device-fingerprint-123"
    }
  ) {
    status
    url
    state
    errorMessage
  }
}

Example Output:

{
  "data": {
    "loginWithSocial": {
      "status": "SUCCESS",
      "url": "https://www.facebook.com/v12.0/dialog/oauth?client_id=...&redirect_uri=...",
      "state": "random_state_string_for_verification",
      "errorMessage": null
    }
  }
}

linkSocial

Link a social account to an existing user account.

mutation LinkSocial($input: LinkSocialInput!) {
  linkSocial(input: $input) {
    status
    url
    state
    errorMessage
  }
}

Input:

input LinkSocialInput {
  type: AuthSocialType!     // The social provider type (GOOGLE, FACEBOOK, etc.)
  redirectPath: String!     // The path where the user will be redirected after authentication
}

Returns:

type GenerateSocialAuthUrlResponse {
  status: ResponseStatus!   // SUCCESS or ERROR
  url: String               // URL to redirect the user to the social provider's auth page
  state: String             // State parameter for CSRF protection
  errorMessage: String      // Error message if status is ERROR
}

Example Input:

mutation {
  linkSocial(input: { type: GOOGLE, redirectPath: "/auth/callback" }) {
    status
    url
    state
    errorMessage
  }
}

Example Output:

{
  "data": {
    "linkSocial": {
      "status": "SUCCESS",
      "url": "https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...",
      "state": "random_state_string_for_verification",
      "errorMessage": null
    }
  }
}

Special Case - Telegram:

If the type is set to TELEGRAM, the mutation will return:

{
  "data": {
    "linkSocial": {
      "status": "ERROR",
      "errorMessage": "NOT_IMPLEMENTED"
    }
  }
}

unlinkSocial

Unlink a social account from a user account.

mutation UnlinkSocial($input: UnlinkSocialInput!) {
  unlinkSocial(input: $input) {
    id
    username
    email
    # other user fields
  }
}

Input:

input UnlinkSocialInput {
  type: AuthSocialType!   // The social provider type to unlink (GOOGLE, FACEBOOK, etc.)
}

Returns:

• UserModel: The updated user object after unlinking the social account

Example Input:

mutation {
  unlinkSocial(input: { type: GOOGLE }) {
    id
    username
    email
  }
}

Example Output:

{
  "data": {
    "unlinkSocial": {
      "id": "user_12345abcde",
      "username": "johndoe123",
      "email": "johndoe@example.com"
    }
  }
}

Special Case - Telegram:

If the type is set to TELEGRAM, the mutation will throw an error with the message "NOT_IMPLEMENTED".

verifySocialAuth

Complete the social authentication process after redirecting from the social provider.

mutation VerifySocialAuth($input: VerifySocialAuthInput!) {
  verifySocialAuth(input: $input) {
    status
    user {
      id
      username
      email
      # other user fields
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Input:

input VerifySocialAuthInput {
  code: String    // The authorization code received from the social provider (optional)
  state: String!  // The state parameter received from the social provider (must match the one sent)
}

Returns:

type LoginResponse {
  status: ResponseStatus!        // SUCCESS or ERROR
  user: UserModel                // The authenticated user's details
  errorMessage: String           // Error message if status is ERROR
  onBoardingCompleted: Boolean   // Whether the user has completed onboarding
  newUser: Boolean               // Whether this is a new user
  mfaPhoneHint: String           // If MFA is enabled, a hint about the phone number
  mfaType: MfaType               // Type of MFA if required for login
  unlocksAt: Date                // When user is no longer restricted from making this request
}

Note: Upon successful authentication, the accessToken and refreshToken are set as HTTP cookies and are not directly returned in the response body.

Example Input:

mutation {
  verifySocialAuth(
    input: {
      code: "auth_code_from_social_provider"
      state: "state_from_social_provider"
    }
  ) {
    status
    user {
      id
      username
      email
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Example Output:

{
  "data": {
    "verifySocialAuth": {
      "status": "SUCCESS",
      "user": {
        "id": "user_12345abcde",
        "username": "johndoe123",
        "email": "johndoe@example.com"
      },
      "errorMessage": null,
      "onBoardingCompleted": true,
      "newUser": false,
      "mfaPhoneHint": null,
      "mfaType": null,
      "unlocksAt": null
    }
  }
}

Social Authentication Flow

1. Initiate the Authentication Flow:

   • Call registerWithSocial, loginWithSocial, or linkSocial with the desired social provider
   • Receive a URL to redirect the user to the social provider's login page

2. User Authenticates with Social Provider:

   • The user logs in on the social provider's page and grants necessary permissions
   • The social provider redirects back to your application with an authorization code

3. Complete the Authentication:

   • Call verifySocialAuth with the code and state received from the social provider
   • The API verifies the credentials and completes the authentication process

Security Considerations

• The state parameter is used to prevent CSRF attacks
• Use HTTPS for all redirects to ensure data security
• Store tokens securely on the client side
• The user must explicitly agree to terms during registration
• Redis-based locks prevent brute force attacks
• Device fingerprinting provides an additional layer of security for identifying trusted devices