Connect BackAuth

The usual process to implement a Social Login is stablishing a connection with the API of each Social Network you may have chosen as a registry method.

With the Xeerpa connect BackAuth product you will only need to stablish a connection with Xeerpa, as the product will take care of these connections itself. That way you don't need to know how each Social Network API works, Xeerpa Connect BackAuth will handle all these connections for you. How?

  • When users click on the login button Xeerpa Connect BackAuth is activated and automatically establishes the connection with the API of the social network selected, authenticating the user.
  • The solution also establishes the connection with the Xeerpa web service in order to analyze the user.
  • Furthermore, Xeerpa Connect BackAuth allows for the addition of more social networks at a later stage, quicker and with greater ease, aleviating your IT team from the task of monitoring for changes to the APIs of the various social networks.


Moreover, Xeerpa Connect BackAuth offers the following advantages::

  • Higher speed in the implementation of the Social Login. Once the connection with Xeerpa has been stablished, adding or removing Social Networks to your Social Login will be a matter of a few seconds.

  • You will not have to worry about any change in the policies of privacy and use of social API data. We will take care of maintaining the product updated.

  • Gather more advanced analytics which will allow you to know the details about the conditions the user has logged in with. We will have get more analytics of the users that have logged in from a SL connected to a XCBA.


This is the basic data flow designed for Xeerpa Connect BackAuth using Facebook:

Flujo BackAuth


Implementing Xeerpa Connect BackAuth


This section assumes you are familiar with the creation and configuration of apps in the desired social networks. To learn more about this please visit the section Social Network Apps.


Step 1: Information you'll need to send us

After choosing and configuring your app with the appropiate Permissions and Callback URL, you need to send the following information about each of your apps to support@xeerpa.com :

App Name:
Name of your app
Social Network:
Social network of your app
API ID/App Id or Key:
App’s ID in the social network
App Secret:
Your App secret from the social network
App's brand ID or name
URL called by a social network after the user accepts to log in. For example,   https://mydomain.com/socialLogin/socialLoginCallback.php
URL called by Xeerpa after the authentication process is completed. For example,   https://mydomain.com/socialLogin/socialLoginCompleted.php
Keep in mind
After this step we will send you an AUTHTOKEN and a PERSONALIZED URL only valid for your server, in order to call the Xeerpa engine. You will need these parameters for the next step


Step 2: Implement the Social Network Login Buttons 


Upon request Xeerpa can provide sample code for implementing step 2 and step 3 of this document for PHP and Node.js. Please do not hesitate to inquire at support@xeerpa.com

2.1 Render your social network buttons in your website or promotion

You will need to implement a button for each Social Network you may have chosen in your Website, Mobile App or Promotion. To design the social login button follow these guidelines:
  • Color: It must be the Social Network's official color.
  • Logo: Use the official logo which will be available in the Brand Guidelines. Do not use old logos or custom variations.
  • Copy: We recommend you to use a phrase related to the call to action. These messages help improve the conversion rate. For example: "Login with.." or "Continue with.."


Configuración Botón De FB ENG 1


These are some examples of the buttons:

Social Login Buttons2


When the user clicks on one of these buttons you must open a new window popup and make a call to your own server to respond to this onclick event.

Keep in mind
Make sure you implement the parameter scrollbar=yes when opening the popup to ensure the view of the whole message in firefox.


2.2 In your server, create the entry point to receive the onclick event from step 2.1  (avoiding the use of the word “Xeerpa” in the url). From there make a GET request to Xeerpa using the following parameters:

CLIENTURL was provided when you registered your app in Xeerpa.
AUTHTOKEN was provided when you registered your app in Xeerpa. 
A reference to the social network chosen by the user to authenticate with.
FB: Facebook, TW: Twitter, LI: LinkedIn, GO: Google, IG: Instagram
id (Optional)
User’s ID in your CRM, when available.
info (Optional):
false by default. If true, Xeerpa will send an extra field with the default user information in a more detailed structure. See Step 2.4
robinson (Optional):
Whether or not the user accepts to receive commercial communications from you. This is typically requested to the user in an opt-in checkbox in your website or app. Set ROBINSON to TRUE if the user does NOT wish to receive them, or to FALSE if he wants to.


Xeerpa will respond with a JSON. If errorCode is not 1 you should deal with the error. Otherwise you mut redirect the popup to the url specified in the response:

Error code value will be 1 if everything is correct.
Error message if any.
URL where the user will need to be redirected to.
Example of call:


Example return value:


“errorCode": 1,

"url": "https://www.facebook.com/dialog/oauth?display=popup&response_type=code&redirect_uri=http%3A%2F%2Ftest.com%2Ftest%2F%2FresponseCallback.php %3Frid%3D5SQR8N9V15_iUaRgbZ1_h_9fjjjjcijb9ha75fc4iicage&scope=public_profile,email,user_friends,user_birthday,user_location,user_likes,user_tagged_places,user_posts&client_id=17347454208“



2.3 Create the socialLoginCallback point in your server (avoid using the word Xeerpa). This will be used one or more times (depending of the social network) to stablish a dialogue between Xeerpa and the social network. The information may arrive in your entry point by GET, POST or both, so it must be aggrupped and then sent to Xeerpa with a GET request. 

CLIENTURL was provided when you registered your app in Xeerpa.
Data received by the popup in by GET and POST methods.


For example, if a social network returns “aaa=123" by GET and "bbb=456“ by POST, you should construct the call to Xeerpa like that:


The response from Xeerpa will be a JSON similar to the step 2.2, and the next step depends of the presence of the property "fields" in the JSON:

  • if there is no "fields" property in the JSON, you can simply redirect the popup to the JSON's url property.
Error code. (1 if successful and no error occurred)
Error message if error code is not 1
URL to redirect the user (when the “fields” parameter is not present)


  • If the response does contain the fields property, you will have to make a POST request to the JSON's url passing the fields value as the body of the request.
Error code. (1 if successful and no error occurred)
Error message if error code is not 1
URL to redirect the user (when the “fields” parameter is not present)
For example, "https://www.linkedin.com/uas/oauth2/accessToken"
Some String to be used as body of the request.
For example, "ccc=789&ddd=0"
POST to https://www.linkedin.com/uas/oauth2/accessToken with body ccc=789&ddd=0

The response will always be a plain text that should be included as a query parameter called "data" to the popup's current url and redirect it to that new address.

redirect the popup to


2.4 Create the socialLoginCompleted point in your server as specified in Step1.1 (avoid using the word Xeerpa). The last redirection made by the socialLoginCallback entry point is to your own server, passing the user information in JSON format.

Error code. (1 if successful and no error occurred)
Error message if error code is not 1

JSON with user’s data. Some data could be empty depending on the Social Network.

Errorcode.(1 if successful and no error occurred)
Success or error message
Xeerpa User ID
Xeerpa User Token
FB: Facebook, TW: Twitter, LI: LinkedIn, GO: Google, IG: Instagram
User ID in the social Network
User token in the social Network
If available in authenticated social network
Xeerpa token expiration date.
Special Xeerpa Token to request a new Xeerpa User Token
The presence of this paramater indicates this is the first time this user has been authentified in Xeerpa 
Object (Available when the info parameter is specified in step 2.1)


At this point you should pass the user information back to your page in the server, using postMessage, cookies or any other method of your preference. You may also securely process the user information and store it on your own database.

Optionally you can call Xeerpa to assign Robinson, a user’s CRM ID or extra data using Xeerpa's user ID and token. Note that these calls should be made from your server (back-end server to server), never from the browser, for security reasons:


The following calls and, in general all calls to Xeerpa unless otherwise specified, should be made from your server, not from the user's browser.

CLIENTURL will be provided when we register your app in Xeerpa
User’s Xeerpa ID: auth.id in Step 2.4
User’s Xeerpa Token: auth.token in Step 2.4
User´s CRM ID
TRUE if the user does not want to receive commercial communications, or FALSE if she/he accepts to receive them
External data in JSON format to insert into the user. Replace the & character with %26 in this parameter.
Will add a Location to the Geolocations Map which can be used as a filter. The format will be a JSON like this: {"id":"FB_OR_CLIENT_ID","name":"Xeerpa","lat":40.42,"lon":-3.78,"date":"2018-09-25T11:23:42.000Z"}. I.E: You can send a WiFi ID to identify the users who logged in at a particular store. See an example below.



Typically, the values sent to Xeerpa in the DATA parameter are added as additional information, but not as the main data points for the user. However, sometimes it is necessary to enforce the values obtained through the form as part of the user profile in Xeerpa. For instance, if the Facebook permission for Birthday is not enabled, the user’s date of birth requested in the registration form can be used instead. In these occasions where the fields from the form will override the data coming from the social network, the parameter data.profile will be used.


In case of sending one or more of the details from this list in data parameter, the JSON should have this format:



 "email":"", - String

 "first_name":"", - String

 "middle_name":"", - String

 "last_name":"", - String

 "gender":"", - String with possible values: "f" for female or "m" for male

 "birthday":"", - String. Format YYYY/MM/DD

 "locale":"", - String in standard locale format according to: https://developers.facebook.com/docs/messenger-platform/messenger-profile/supported-locales/

 "hometown":"", - String

 "location":"" - String


"":"" – String. Supports an unlimited number of extra fields



Finally you can close the popup or display a widget that helps you getting some social networks' special permissions. For more information read the next step.


Step 3: Obtain advanced user permissions

For Xeerpa to be able to gather and process the most important social information from the Facebook users, the Facebook Application linked to your Facebook Xeerpa Connection must be allowed to request the permissions to extract the advanced details. You can find more information about these permissions here.

Facebook reviews all the permission requests for every Facebook App, and this approval must be granted once for each Facebook App. You can use the Xeerpa Connect Summary Widget to obtain these permissions (user_birthday, user_location, user_posts, user_tagged_places, user_gender, user_friends and user_likes) - please feel free to request any further information about this Widget, contacting us through support@xeerpa.com.


Using Xeerpa Connect Summary Widget for Facebook

This Widget will be returned by Xeerpa as a JSON with some basic HTML which can be customized to match the look and feel of your website, mobile applicaiton, or WiFi hotspot, and can be extended to provide a more personalized user experience. Please check our Summary Widget article.

The Summary Widget call is already implemented in the Connect BackAuth PHP files, though in case you prefer to add the calls to your own PHP file, you can manually implement the Summary Widget making this call:

CLIENTURL will be provided when we register your app in Xeerpa
User’s Xeerpa ID:  'id' in Step 2.4
User’s Xeerpa Token: token in Step 2.4
LANG (Optional)
Language: EN: English. ES: Spanish. CA: Catalan. EN by default.
TAB (Optional)
USER | LIKES | PLACES. By default none. Which tab will be show expanded by default.
CSS (Optional)
TRUE | FALSE. TRUE by default. If TRUE Xeerpa will send a default css.
Keep in mind
Your website must not contain any '#fb' style set in the CSS.