# Authentication

The Socios.com 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](https://partner-integration.socios.com/devportal/apis).
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.

{% hint style="warning" %}
If you don’t already have an application registered in the DevPortal, you have the possibility to create one or more applications. See the [Prerequisites](https://connect.socios.com/partner-api/prerequisites) section for more information.
{% endhint %}

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

{% hint style="info" %}
**In short**

If the API endpoint *does not* contain 'user' in the route, you need 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 need an access token obtained via the Authorisation Code Flow (Socios.com Connect).

For instance:

* `GET /user/polls`
* `GET /user/poll/{pollId}`
* `POST /user/poll/{pollId}/vote`
  {% endhint %}

## OAuth - Client Credentials Flow

{% hint style="info" %}
**Reminder**\
This flow is used when your application just needs read-only access to public information.
{% endhint %}

### **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](https://en.wikipedia.org/wiki/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` .&#x20;

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](https://curl.se/):

{% code overflow="wrap" %}

```bash
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" 
```

{% endcode %}

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

```json
{
    "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:

{% code overflow="wrap" %}

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

{% endcode %}

## OAuth - Authorization Code Flow

{% hint style="info" %}
**Reminder**\
This flow allows your application to access user's data on their behalf, but only after obtaining the user's permission.&#x20;
{% endhint %}

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](https://oauth.net/code/) 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.

<figure><img src="https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2F5hxLuS5a966XIdPxXYQN%2Fimage.png?alt=media&#x26;token=4f9fa387-77db-4826-a539-75689de8d1ac" alt=""><figcaption></figcaption></figure>

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:

<table><thead><tr><th width="183.33333333333331">Parameter</th><th width="477">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>response_type</code></td><td>Simply use the word "code".</td><td>Yes </td></tr><tr><td><code>client_id</code></td><td>This is the client ID you got when you set up your application.</td><td>Yes</td></tr><tr><td><code>partner_tag</code></td><td>This is your DevPortal username.</td><td>Yes</td></tr><tr><td><code>redirect_uri</code></td><td>This is the web address in your app where users will be sent after authorisation. It needs to be URL encoded.</td><td>Yes</td></tr></tbody></table>

This is what the authorisation URL might look like:

{% code overflow="wrap" %}

```http
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
```

{% endcode %}

For instance, with fake data:

{% code overflow="wrap" %}

```http
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
```

{% endcode %}

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

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

For instance, with fake data:

{% code overflow="wrap" %}

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

{% endcode %}

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

<table><thead><tr><th width="183.33333333333331">Parameter</th><th width="416">Description</th></tr></thead><tbody><tr><td><code>grant_type</code></td><td>Value <code>(authorisation code)</code></td></tr><tr><td><code>code</code></td><td>Value from Step 2</td></tr><tr><td><code>client_id</code></td><td>The client ID you received after registering your application.</td></tr><tr><td><code>client_secret</code></td><td>The client secret you received after registering your application.</td></tr><tr><td><code>redirect_uri</code></td><td>The client secret you received after registering your application.</td></tr></tbody></table>

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:

{% code overflow="wrap" %}

```bash
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'

```

{% endcode %}

For instance, with fake data:

{% code overflow="wrap" %}

```bash
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'
```

{% endcode %}

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

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

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

For instance, with fake data:

{% code overflow="wrap" %}

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

{% endcode %}

### Step 4: Call the API

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

Here's an example using curl:

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

```json
{
    "data":
    "userId": "USER_ID"
}
```

For example, with fake data:

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

You can of course make an API call from any tool, such as [Postman](https://www.postman.com/):

<figure><img src="https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Far18qNOY1utuDHnyxwP8%2Fimage.png?alt=media&#x26;token=1c691f58-046c-415b-9ae5-9a6452d606e9" alt=""><figcaption></figcaption></figure>

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:

{% code overflow="wrap" %}

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

{% endcode %}

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

The expected JSON response would look like this:

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

Expiration example :

* Refresh Token Expiry Time : 90d (7776000) &#x20;
* Access token : 24h (86400)

<figure><img src="https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FlGCXAw6c8coJph87xqBy%2Fimage%20(4).png?alt=media&#x26;token=a61772b8-a6d2-4277-a98f-b3466f7d88f3" alt=""><figcaption></figcaption></figure>

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

{% code overflow="wrap" %}

```bash
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
```

{% endcode %}

{% hint style="info" %}
You will receive a `200 OK` for both successful and unsuccessful requests.
{% endhint %}

## 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` | <p>ID of the campaign from the marketing tool<br><em>Can be empty</em></p>    |
| `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.