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. Snag supports connecting the following social platforms:

Twitter
Discord
Telegram
Epic Games
Steam
Google
Tiktok
Email

Endpoint

GET /api/{authType}/auth

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

Query Parameters

Parameter	Type	Required	Description
userId	UUID	Yes	The ID of the user received from the user creation endpoint
websiteId	UUID	No	The ID of the website (if applicable)
redirect	String	Yes	The URL where the user will be redirected after completing authentication
responseType	String	No	The 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

Call the /api/{authType}/auth endpoint with the required parameters
The API will return a URL that you should redirect your user to
The user will authenticate with the social platform and grant permissions
After successful authentication, the user will be redirected to the URL specified in the redirect parameter
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

Parameter	Type	Required	Description
emailAddress	String	Yes	The user’s email address to verify.
redirect	String	No	URL to redirect the user to after verification. We append `status` and, on failure, optional `error`.
userId	UUID	Conditional	Required when calling server-to-server with an API key to target a specific user.
walletAddress	String	Conditional	Alternative to `userId` when calling server-to-server with an API key; creates/links a user by wallet.
websiteId	UUID	No	Your website identifier if applicable.

Headers

x-api-key: Required.

Flow

Initiate email verification

Call the endpoint with emailAddress (and optional redirect). This stores the pending email on the user’s metadata and sends a verification email containing a secure link.

curl -X GET 'https://admin.snagsolutions.io/api/email/auth' \
  -H 'x-api-key: YOUR_SNAG_API_KEY' \
  -G \
  --data-urlencode '[email protected]' \
  --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" }

User clicks verification link

The email contains a link to GET /api/email/auth/connect?token=.... Snag validates the token and verifies the email.

Handle the final redirect

After verification, the user is redirected to your redirect URL (or a default verification page) with a status:

status=SUCCESS on success
status=EXPIRED if the link expired
status=INVALID and error=INVALID_CODE for invalid tokens

Example: https://your-app.com/email-verified?status=SUCCESS

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. If the social account is already associated with a different user, the redirect URL will include two query parameters:

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

In this case, you should:

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
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:

Display a user-friendly message explaining that a YouTube channel is required
Prompt the user to create a YouTube channel first
Provide instructions on how to create a YouTube channel
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://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 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. 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.

Introduction

Loyalty

Create

Stratus

Marketplace

AI

Managing social accounts

Overview

Endpoint

Query Parameters

Example Request

Authentication Flow

Connecting Email

Endpoint

Query Parameters

Headers

Flow

Handling Email Account Conflicts

Google OAuth YouTube Channel Errors

Example Implementation with Conflict Handling

Example Tiktok Implementation

Example Implementation

Response Handling

Success Response (200 OK)

Custom OAuth Applications

Next Steps

Introduction

Loyalty

Create

Stratus

Marketplace

AI

​Overview

​Supported Social Platforms

​Connecting a Social Account

​Endpoint

​Query Parameters

​Example Request

​Authentication Flow

​Connecting Email

​Endpoint

​Query Parameters

​Headers

​Flow

​Handling Email Account Conflicts

​Handling Social Account Conflicts

​Google OAuth YouTube Channel Errors

​Example Implementation with Conflict Handling

​Example Tiktok Implementation

​Example Implementation

​Response Handling

​Success Response (200 OK)

​Custom OAuth Applications

​Next Steps

Overview

Supported Social Platforms

Connecting a Social Account

Endpoint

Query Parameters

Example Request

Authentication Flow

Connecting Email

Endpoint

Query Parameters

Headers

Flow

Handling Email Account Conflicts

Handling Social Account Conflicts

Google OAuth YouTube Channel Errors

Example Implementation with Conflict Handling

Example Tiktok Implementation

Example Implementation

Response Handling

Success Response (200 OK)

Custom OAuth Applications

Next Steps