Authentication

The Socios.com Partner API uses the OAuth 2.0 protocol to secure the endpoints that we provide. By using OAuth, developers receive a unique user ID, then use an access token for allowed resources like Polls, Socios.com profile data, etc.

Obtain your API keys

Once you have obtained your credentials from Socios.com, you must generate the API keys from the developer portal.

Follow the steps below:

1. Login to Socios.com Developer Portal.

2. Go to the Applications section, in the top menu bar.

3. Open the application for which you want the access tokens.

4. Open the OAuth2 Keys page, in the left side bar.

There, you'll find both the consumer key and the consumer secret.

If you don’t already have an application, you have the possibility to create one or more applications. See the Prerequisites section for more information.

Choose Your OAuth Flow

You can choose from two OAuth flows:

• Client Credentials Flow This is used when your application just needs read-only access to public information. Here, a pair of client credentials (client_id and client_secret) are exchanged for an access token. NOTE: This authentication doesn't include user data.

• Authorization Code Flow (Socios.com Connect) This allows your application to access user's data on their behalf, but only after obtaining the user's permission. With this flow, an application can acquire more sensitive, opt-in information about a user and interact with the user data.

In short

If the API endpoint does not contain 'user' in the route, you must use an access token obtained via the Client Credentials Flow.

For instance:

• GET /polls/{{version}}/polls

• GET /polls/{{version}}/poll/{pollId}

If the API endpoint does contain 'user' in the route, you'll need an access token retrieved via the Authorisation Code Flow (Socios.com Connect).

For instance:

• GET /user/polls

• GET /user/poll/{pollId}

• POST /user/poll/{pollId}/vote

OAuth - Client Credentials Flow

Reminder This flow is used when your application just needs read-only access to public information.

Step 1: Make your key and secret ready for use

To prepare your application's consumer key and consumer secret, follow these steps:

1. Concatenate the consumer key, a colon symbol (":"), and the consumer secret into one string.

2. Use Base64 to encode the string you just made. It should look like this: <Base64(client_id:client_secret)>

Step 2: Get your access token

Your application needs to ask for access tokens by sending a POST request with the following multipart form data to the token URI: grant_type=client_credentials .

The application needs to include the encoded key and secret you made in step 1.

This is an example of what the request looks like, using curl:

curl -k -v https://partner.socios.com/oauth2/token
     -d "grant_type=client_credentials" 
     -H "Authorization: Basic cEJ6dUlaaEdwaGZRbWRjVVgwbG5lRmlpdXh3YTo0U0pnV19qTU56aGpIU284OGJuZVhtTnFNMjRh" 
     -H "Content-Type: application/x-www-form-urlencoded" 

If all goes well, you'll get a response that looks like this:

{
    "token_type":"bearer",
    "access_token":"(a really long string of characters)"
}

Step 3: Use your access token

Once you've got your access token, you can use it to ask for information from the API resources. You do this by including it in an authorization header when making HTTPS requests, with the value of Bearer as <base64 bearer access_token value from step 2>

Here is an example using curl:

curl --request GET \
  --url https://api-public.socios.com/survey/<apiVersion>/survey/surveys \
  -H 'Authorization: Bearer (a really long string of characters)

OAuth - Authorization Code Flow

Reminder This flow allows your application to access user's data on their behalf, but only after obtaining the user's permission.

To get the user’s permission (and an authorization code), your application will need to direct the user's browser or open a new window to a special web address (URL) with some specific details. We advise you to use an established OAuth2 library for your OAuth client, where you just input your client id, secret, and other details.

If you choose to use an OAuth2 library for your server application, make sure to follow the documentation from the library. If you choose to not use an OAuth2 library, you can set things up manually by following the following guide...

Step 1: Redirect users to request access to Socios.com

First of all, go the DevPortal, and open your application's Product Keys page. There, make sure to check the code case in the Grant Types section.

You need to send the user to Socios.com to approve access to your application. This is done by creating an authorization URL with the correct details. The following details must always be included:

Parameter	Description	Required
response_type	Simply use the word "code".	Yes
client_id	This is the client ID you got when you set up your application.	Yes
partner_tag	This is your DevPortal username.	Yes
redirect_uri	This is the web address in your app where users will be sent after authorisation. It needs to be URL encoded.	Yes

This is what the authorisation URL might look like:

GET https://partner.socios.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL?partner_tag=YOUR_PARTNER_TAG

For instance, with fake data:

GET https://partner.socios.com/oauth2/authorize?response_type=code&client_id=1532**c**63424622b6e9**c**4654e7f97ed40194a1547e114ca1**c**682f44283f39dfa49&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&partner_tag=yourteam

Step 2: Socios.com sends users back to your site

Once the user approves your application, Socios.com will send them back to your web address with a temporary code. It might look something like this:

GET https://example.com/oauth/callback?code=TEMPORARY_CODE

For instance, with fake data:

GET https://example.com/oauth/callback?code=4**c**666b5**c**0**c**0d9d3140f2e0776cbe245f3143011d82b7a2**c**2a590**cc**7e20b79ae8

Step 3: Swap the temporary code for an access token

Now that you have the temporary authorisation code, you can swap it for valid access and refresh tokens. You do this by making a POST call to the https://partner.socios.com/oauth2/token URL with the following parameters:

Parameter	Description
grant_type	Value (authorisation code)
code	Value from Step 2
client_id	The client ID you received after registering your application.
client_secret	The client secret you received after registering your application.
redirect_uri	The client secret you received after registering your application.

Note: All parameters are mandatory

• grant_type: Use authorization_code.

• code: Use the value from step 2.

• client_id: The client ID you received after registering your application.

• client_secret: The client secret you received after registering your application.

• redirect_uri: The same redirect_uri used when obtaining the authorisation.

The call would take this shape with curl, for instance:

curl https://partner.socios.com/oauth2/token
     -X POST
     -d 'grant_type=authorization_code&code=TEMPORARY_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=YOUR_REDIRECT_URL'

For instance, with fake data:

curl https://partner.socios.com/oauth2/token
  -X POST
  -d 'grant_type=authorization_code&code=4c666b5c0c0d9d3140f2e0776cbe245f3143011d82b7a2c2a590cc7e20b79ae8&client_id=1532c63424622b6e9c4654e7f97ed40194a1547e114ca1c682f44283f39dfa49&client_secret=3a21f08c585df35c14c0c43b832640b29a3a3a18e5c54d5401f08c87c8be0b20&redirect_uri=https://example.com/oauth/callback'

And here's the JSON data you would get back:

After a successful request, you will receive a valid access token:

{
    "access_token": "ACCESS_TOKEN",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "REFRESH_TOKEN"
}

For instance, with fake data:

{
    "access_token": "6915ab99857fec1e6f2f6c078583756d0c09d7207750baea28dfbc3d4b0f2cb80",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "73a3431906de603504c1e8437709b0f47d07bed11981fe61b522278a81a9232b7"
}

Step 4: Call the API

Once you have a valid access token, you're ready to make your first API call.

Here's an example using curl:

curl https://api-public.socios.com/user/1.0.0/user/me 
     -H 'Authorization: Bearer ACCESS_TOKEN'

The expected JSON response would look like this:

{
    "data":
    "userId": "USER_ID"
}

For example, with fake data:

{
  "data": {
    "userId": "b87450af-e752-4c61-8e66-65f129297b10"
  }
}

You can of course make an API call from any tool, such as Postman:

And that's it! Your app is now authenticated using OAuth 2.0 in a user context, without using an OAuth2 library.

Generate a new access token and refresh token

You might want to create a new set of tokens, for security reasons or just to maintain the integrity of the authentication process. Here is how.

Use the following commands:

curl https://partner.socios.com/oauth2/token
     -X POST
     -d 'grant_type=refresh_token&refresh_token=<refresh-token>'

Replace the <refresh-token> value with the refresh token generated in the previous step.

The expected JSON response would look like this:

{
    "scope":"default",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"7ed6bae2b1d36c041787e8c8e2d6cbf8",
    "access_token":"b7882d23f1f8257f4bc6cf4a20633ab1"
}

Expiration example :

• Refresh Token Expiry Time : 90d (7776000)

• Access token : 24h (86400)

Revoke an access token

You might want to stop your application from accessing a user's account, or to include a log-out feature in your application. You can do this by revoking the relevant access token.

To revoke an access token, you'll need to send a POST request. The request should include the access token you want to revoke and your application's encode consumer key and consumer secret.

You can revoke access manually, or include it as part of a log out feature.

Here's an example of how you do it using curl:

curl -k -v 
     -d "token=<ACCESS_TOKEN_TO_BE_REVOKED>" 
     -H "Authorization: Basic <base64 encoded (consumerKey:consumerSecret)>" 
     -H "Content-Type: application/x-www-form-urlencoded" 
     https://partner.socios.com/oauth2/revoke

You will receive a 200 OK for both successful and unsuccessful requests.

Adding tracking parameters

For the purpose of tracking, you can add the following parameters to the URL:

Parameter	Description
referrer	Name of the third party
campaign	ID of the campaign from the marketing tool Can be empty
param1	The platform where our campaign is located (website / mobile / display, etc.)
param2	The page where our campaign is located (homePage, matchPage, etc.)
param3	The type of integration (banner / iframe / API)

By setting these parameters properly, we can share conversion data with you, please make sure to review it with people from Chiliz/Socios to make sure it makes sense.