​
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

​
Connecting a Social Account

​
Endpoint

GET /api/{authType}/auth
Where {authType} is one of: twitter, discord, telegram, epic, or steam or google.

​
Query Parameters

ParameterTypeRequiredDescription
userIdUUIDYesThe ID of the user received from the user creation endpoint
websiteIdUUIDNoThe ID of the website (if applicable)
redirectStringYesThe URL where the user will be redirected after completing authentication
responseTypeStringNoThe type of response to return (redirect or json). Defaults to redirect

​
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

​
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
YouTube channels are automatically created when users upload their first video or customize their channel. Users can also manually create a channel by visiting youtube.com and following the setup prompts.

​
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://api.snagsolutions.io/api/users/verify',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${process.env.SNAG_API_KEY}`,
        },
        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 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://api.snagsolutions.io/api/twitter/auth?userId=${userId}&redirect=https://your-app.com/auth-callback`,
      {
        headers: {
          Authorization: `Bearer ${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. If you would like to use your own client ID and client secret for any of these platforms, please contact the Snag team for integration support. We’ll guide you through the process of setting up and configuring your custom OAuth applications with our system. 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

​
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.