Managing social accounts

Overview

This guide explains how to use Snag's social integration API to let your users connect their social accounts to their Snag profile. After creating a user in Snag (as explained in Managing User Accounts), you can use the social authentication endpoints to connect various social platforms to that user's profile.

Supported Social Platforms

Snag supports connecting the following social platforms:

• Twitter
• Discord
• Telegram
• Epic Games
• Steam
• Google
• Tiktok
• Email
• Reddit
• Phone

Connecting a Social Account

Endpoint

GET /api/{authType}/auth

Where {authType} is one of: twitter, discord, telegram, epic, steam , google , Reddit or tiktok.

Query Parameters

Example Request

GET /api/twitter/auth?userId=123e4567-e89b-12d3-a456-426614174001&redirect=https://your-app.com/auth-callback

Authentication Flow

1. Call the /api/{authType}/auth endpoint with the required parameters
2. The API will return a URL that you should redirect your user to
3. The user will authenticate with the social platform and grant permissions
4. After successful authentication, the user will be redirected to the URL specified in the redirect parameter
5. The social account is now connected to the user's Snag profile

Connecting Email

Use this flow to associate and verify a user's email with their Snag profile.

Endpoint

GET /api/email/auth

Query Parameters

Headers

• x-api-key: Required.

Flow

curl -X GET 'https://admin.snagsolutions.io/api/email/auth' \
  -H 'x-api-key: YOUR_SNAG_API_KEY' \
  -G \
  --data-urlencode 'emailAddress=user@example.com' \
  --data-urlencode 'userId=123e4567-e89b-12d3-a456-426614174001' \
  --data-urlencode 'redirect=https://your-app.com/email-verified'

{ "message": "Verification email sent.", "userId": "123e4567-e89b-12d3-a456-426614174001" }

Handling Email Account Conflicts

If the email is already verified for another user on the same website, the user is redirected to your redirect with error=MAXIMUM_ACCOUNT_LINKED. Handle this scenario the same way as described in Handling Social Account Conflicts.

Connecting Phone

Use this flow to associate and verify a user's phone number with their Snag profile. Phone verification uses Twilio Verify to send an OTP code via SMS.

Step 1: Send Verification Code

Endpoint

POST /api/phone/auth

Headers

• x-api-key: Required.
• Content-Type: application/json

Body Parameters

Step 2: Verify OTP Code

Endpoint

POST /api/phone/auth/connect

Headers

• x-api-key: Required.
• Content-Type: application/json

Body Parameters

Flow

curl -X POST 'https://admin.snagsolutions.io/api/phone/auth' \
  -H 'x-api-key: YOUR_SNAG_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+14155552671",
    "userId": "123e4567-e89b-12d3-a456-426614174001"
  }'

{
  "message": "Verification code sent.",
  "userId": "123e4567-e89b-12d3-a456-426614174001"
}

curl -X POST 'https://admin.snagsolutions.io/api/phone/auth/connect' \
  -H 'x-api-key: YOUR_SNAG_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+14155552671",
    "code": "123456",
    "userId": "123e4567-e89b-12d3-a456-426614174001"
  }'

{
  "success": true,
  "message": "Phone number verified."
}

Disconnecting Phone

To disconnect a phone number from a user's profile:

POST /api/phone/auth/disconnect

curl -X POST 'https://admin.snagsolutions.io/api/phone/auth/disconnect' \
  -H 'x-api-key: YOUR_SNAG_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "123e4567-e89b-12d3-a456-426614174001"
  }'

{
  "message": "Phone disconnected."
}

Handling Phone Account Conflicts

If the phone number is already verified for another user on the same website, the verify endpoint returns error: 'MAXIMUM_ACCOUNT_LINKED' in the response body:

{
  "success": false,
  "error": "MAXIMUM_ACCOUNT_LINKED",
  "message": "This phone number is already linked to another account."
}

Handle this scenario the same way as described in Handling Social Account Conflicts.

Handling Social Account Conflicts

If the social account is already associated with a different user, the redirect URL will include two query parameters:

1. error = 'MAXIMUM_ACCOUNT_LINKED' - Indicates that the account is already linked to another user
2. accountLinkData - A JWT verification token that contains the necessary information to process the account transfer

In this case, you should:

1. Display a confirmation prompt to the user asking if they want to disconnect the account from the other user and link it to their current profile
2. If the user confirms, make a POST request to /api/users/verify with the following payload:

{
  "accountLinkData": "jwt_verification_token",
  "userId": "current_user_id"
}

This will:

• Disconnect the social account from the previous user
• Connect it to the current user's profile

Google OAuth YouTube Channel Errors

When using Google OAuth, if the user's YouTube channel does not exist, the API will return an error with error = 'YOUTUBE_CHANNEL_NOT_FOUND'. This typically happens when:

• The user has never created a YouTube channel
• The YouTube channel was deleted or suspended
• The user's Google account doesn't have YouTube access

To handle this error, you should:

1. Display a user-friendly message explaining that a YouTube channel is required
2. Prompt the user to create a YouTube channel first
3. Provide instructions on how to create a YouTube channel
4. Allow the user to retry the Google OAuth flow after creating their channel

Google OAuth Requirements

When using Google OAuth integration, whether with Snag's default OAuth application or your own custom OAuth application, you need to ensure the following permissions (scopes) are configured:

• https://www.googleapis.com/auth/youtube.readonly - Required to read YouTube channel information
• https://www.googleapis.com/auth/userinfo.email - Required to access user email address
• https://www.googleapis.com/auth/userinfo.profile - Required to access user profile information

Example Implementation with Conflict Handling

// Server-side implementation (e.g., in Node.js/Express)
app.get('/auth-callback', async (req, res) => {
  const { error, accountLinkData } = req.query
  const userId = req.session.userId // Get from authenticated session

  if (error === 'MAXIMUM_ACCOUNT_LINKED') {
    // Render a confirmation page or return JSON response
    return res.json({
      requiresConfirmation: true,
      accountLinkData,
    })
  }

  if (error === 'YOUTUBE_CHANNEL_NOT_FOUND') {
    // Handle YouTube channel not found error
    return res.json({
      error: 'YOUTUBE_CHANNEL_NOT_FOUND',
      message:
        'YouTube channel not found. Please create a YouTube channel first and then re-authenticate via Google OAuth.',
      requiresChannelCreation: true,
    })
  }

  // Handle successful connection
  res.redirect('/profile')
})

// Handle confirmation
app.post('/confirm-account-transfer', async (req, res) => {
  const { accountLinkData, userId } = req.body

  try {
    const response = await fetch(
      'https://admin.snagsolutions.io/api/users/verify',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': `${process.env.SNAG_API_KEY}`, // API key stored securely on server
        },
        body: JSON.stringify({
          accountLinkData,
          userId,
        }),
      }
    )

    if (response.ok) {
      res.redirect('/profile')
    } else {
      throw new Error('Failed to transfer account')
    }
  } catch (error) {
    console.error('Error transferring account:', error)
    res.status(500).send('Error transferring account')
  }
})

Example Tiktok Implementation

// Server-side implementation (e.g., in Node.js/Express)
app.get('/connect-tiktok', async (req, res) => {
  const userId = req.query.userId // Get from authenticated session
  const redirectUrl = 'https://example.com/tiktok-redirect'

  try {
    // Step 1: Get state (JWT) from your server
    // This initiates the TikTok OAuth flow and returns a JWT containing the verification code
    const response = await fetch(
      `https://admin.snagsolutions.io/api/tiktok/auth?userId=${userId}&redirect${redirect_uri}`,
      {
        headers: {
          'x-api-key': `${process.env.SNAG_API_KEY}`, // API key stored securely on server
        },
      }
    )

    const data = await response.json()

    // The response contains a `state` (JWT).
    // Decode the JWT to extract the 8-digit code that the user must add to their TikTok bio.
    res.json(data)
  } catch (error) {
    console.error('Error initiating TikTok connection:', error)
    res.status(500).send('Error initiating TikTok connection')
  }
})

app.get('/tiktok-redirect', async (req, res) => {
  const { error, state, code } = req.query

  if (error === 'INVALID_TIKTOK_CODE') {
    // Step 1: Handle TikTok verification failure
    // - show error to user
    // - Log the failure for debugging
    // - Optionally redirect to error page or show error message
  }

  // Step 2: If no error,
  // - Call user endpoint
  // - Verify the TikTok connection was successful (tiktokUser,tiktokUserId,tiktokVerifiedAt)
})

// Client-side code to initiate the flow
function decodeJwtForCode(stateJwt) {
  if (!stateJwt || typeof stateJwt !== 'string') {
    throw new Error('Invalid state JWT')
  }

  const decoded = jwt.decode(stateJwt)
  if (decoded && typeof decoded === 'object' && 'generatedCode' in decoded) {
    return decoded.generatedCode
  }

  throw new Error('generatedCode not found in JWT')
}

async function connectTiktokAccount(userId, tiktokProfileUrl) {
  // Step 1: Get state (JWT) from your server
  const response = await fetch(`/connect-tiktok?userId=${userId}`)
  const { state } = await response.json()

  // Decode JWT → extract the 8-digit code
  const code = decodeJwtForCode(state)

  // Show popup asking user to add code to TikTok bio
  if (
    window.confirm(
      `Please add this code to your TikTok bio: ${code}\n\nClick OK once you have updated your bio.`
    )
  ) {
    // Step 2: Redirect user to TikTok connect with state and tiktokProfileUrl
    // After verification, they'll be redirected back to your redirect URL
    const connectUrl = `https://admin.snagsolutions.io/api/tiktok/auth/connect?state=${state}&tiktokProfileUrl=${encodeURIComponent(
      tiktokProfileUrl
    )}`

    window.location.href = connectUrl
  } else {
    console.log('User cancelled TikTok bio update')
  }
}

Example Reddit Implementation

// Server-side implementation (e.g., in Node.js/Express)
app.get('/connect-reddit', async (req, res) => {
  const userId = req.query.userId // Get from authenticated session

  try {
    // Step 1: Get state (JWT) from your server
    // This initiates the Reddit verification flow and returns a JWT containing the verification code
    const response = await fetch(
      `https://admin.snagsolutions.io/api/reddit/auth?userId=${userId}&responseType=json`,
      {
        headers: {
          'x-api-key': `${process.env.SNAG_API_KEY}`, // API key stored securely on server
        },
      }
    )

    const data = await response.json()

    // The response contains a `state` (JWT).
    // Decode the JWT to extract the 8-digit code that the user must add to their Reddit bio.
    res.json(data)
  } catch (error) {
    console.error('Error initiating Reddit connection:', error)
    res.status(500).send('Error initiating Reddit connection')
  }
})

// Client-side code to initiate the flow
function decodeJwtForCode(stateJwt) {
  if (!stateJwt || typeof stateJwt !== 'string') {
    throw new Error('Invalid state JWT')
  }

  const decoded = jwt.decode(stateJwt)
  if (decoded && typeof decoded === 'object' && 'generatedCode' in decoded) {
    return decoded.generatedCode
  }

  throw new Error('generatedCode not found in JWT')
}

async function connectRedditAccount(userId, redditProfileUrl) {
  // Step 1: Get state (JWT) from your server
  const response = await fetch(`/connect-reddit?userId=${userId}`)
  const { state } = await response.json()

  // Decode JWT → extract the 8-digit code
  const code = decodeJwtForCode(state)

  // Show popup asking user to add code to Reddit bio
  if (
    window.confirm(
      `Please add this code to your Reddit bio: ${code}\n\nClick OK once you have updated your bio.`
    )
  ) {
    // Step 2: Call Reddit connect API with state and redditProfileUrl
    const connectUrl = `https://admin.snagsolutions.io/api/reddit/auth/connect?state=${state}&redditProfileUrl=${encodeURIComponent(
      redditProfileUrl
    )}`

    const connectResponse = await fetch(connectUrl)
    const result = await connectResponse.json()

    if (result.success) {
      alert('Reddit account connected successfully!')
    } else {
      alert(result.message || 'Failed to connect Reddit account')
    }
  } else {
    console.log('User cancelled Reddit bio update')
  }
}

Example Implementation

// Server-side implementation (e.g., in Node.js/Express)
app.get('/connect-twitter', async (req, res) => {
  const userId = req.query.userId // Get from authenticated session

  try {
    const response = await fetch(
      `https://admin.snagsolutions.io/api/twitter/auth?userId=${userId}&redirect=https://your-app.com/auth-callback`,
      {
        headers: {
          'x-api-key': `${process.env.SNAG_API_KEY}`, // API key stored securely on server
        },
      }
    )

    const data = await response.json()

    // Redirect the user to the authentication URL
    res.redirect(data.url)
  } catch (error) {
    console.error('Error connecting Twitter account:', error)
    res.status(500).send('Error connecting Twitter account')
  }
})

// Client-side code to initiate the flow
function connectTwitterAccount(userId) {
  // Redirect to your server endpoint
  window.location.href = `/connect-twitter?userId=${userId}`
}

Response Handling

Success Response (200 OK)

{
  "url": "https://auth-provider.com/oauth/authorize?client_id=xxx&redirect_uri=xxx&state=xxx"
}

The url property contains the authentication URL that you should redirect your user to.

Custom OAuth Applications

Snag allows you to use your own OAuth applications for Twitter, Discord, Epic Games, Google, and Steam integrations. This enables you to maintain your brand identity throughout the authentication flow and have more control over the user experience.

To configure your own OAuth credentials, navigate to the Integrations tab in your admin dashboard and enter your client ID and client secret for the desired platform. The changes take effect immediately for all new authentication requests.

You will also need to add the following redirect URLs to your OAuth application:

• https://snag-render.com/api/twitter/auth/callback
• https://snag-render.com/api/discord/auth/callback
• https://snag-render.com/api/epic/auth/callback
• https://snag-render.com/api/steam/auth/callback
• https://snag-render.com/api/google/auth/callback

Google OAuth Application Setup

When configuring a custom Google OAuth application, ensure your OAuth consent screen includes the following required scopes:

• https://www.googleapis.com/auth/youtube.readonly
• https://www.googleapis.com/auth/userinfo.email
• https://www.googleapis.com/auth/userinfo.profile

Troubleshooting

403 Forbidden Response

If you receive a 403 Forbidden response when attempting to connect a social account, check the following:

headers: {
  'x-api-key': 'YOUR_SNAG_API_KEY'
}

Next Steps

After connecting social accounts, you can use this information to enhance the user experience in your application and leverage it for loyalty program features.