Authentication/authorization

We currently support two ways of doing authentication and authorization: either through simple login or with OAuth2

Simple

The first thing to do is a login. To do so, you need to send a POST request to https://api.brandindex.com/v0/login with the email and password parameters, then store the response cookies somewhere so that you can use your session later for using protected API endpoints.

All protected endpoints require that you're already logged in, so you should send back the cookies you received after logging in when using them.

URL
https://api.brandindex.com/v0/login
HTTP methods
POST - if you're effectively logging in
GET - if you're already logged in but want to take a look at the API results
Required parameters (POST)
email - the same e-mail you use to login in BrandIndex.
password - the same password you use to login in BrandIndex.
HTTP statuses
200 - login successful
401 - login failed (POST)
403 - not authenticated (GET)
Response body example

{
  "data": {
    "Company default data": "https://api.brandindex.com/v0/company/defaults"
  },
  "ok": true
}

The ok element is present in all of the API responses, indicating if the request was successful or not. It can be used if you don't want to rely only on HTTP status codes (but it's preferable you check the HTTP status codes instead of the ok element).

The data element is present only on successful responses, and can contain either a JavaScript Object or an Array, depending on the endpoint. In this case, it contains an Object, whose only item's value is the URL for the company default data.

OAuth2

By using the BrandIndex API through OAuth2 we can ensure much more security for the users, as well as privacy over their data.

In the BrandIndex we use OpenID Connect 1.0, which is a simplification layer on top of OAuth2.

Configuration

Before even starting to use OAuth2 you'll need to get the client ID and the client secret. Please contact YouGov so that they can provide them for you. You will need to use them for some of the OAuth2 steps.

Main flow

With this flow your application will be able to get an access token to use when retrieving protected user data.

Authentication

First the application needs to direct the user to the authentication page: https://login.yougov.com/oauth/authorize?response_type=code&scope=brandindex&client_id=your-client-id&redirect_uri=your-callback-url

After this step, the user will hit a login page in YouGov and, after logging in, she will be able to choose wether to allow or not the client app to have access to her data.

Then, our server will redirect the user to the redirect_uri callback parameter provided by the client app, but adding a code parameter to the URL query string. For example, let's say the client app provided https://example.com/my-app/callback as the redirect_uri; the user will then be redirected to a URL similar to https://example.com/my-app/callback?code=some-auth-code. This code will be used in the next step.

URL
https://login.yougov.com/oauth/authorize
HTTP methods
GET
Required parameters
response_type - this should be fixed to a string with the value: "code".
scope - this should be fixed to a string with the value: "brandindex".
client_id - your client ID.
redirect_uri - a URL that will be called back when the login server provides your client app the authentication code (which will be used to request the access token). The code will be provided to this URL by adding the code query string parameter to it.
HTTP statuses
200 - authentication successful, access granted.
400 - access denied.
Response body example

The response body should be ignored, as your client app should use the code as provided in the callback URL's query string via the code parameter.

Access token

Now it's time to get the access token, which can be used for subsequent requests during the token lifetime.

In order to get it, the client app will need to issue a POST request to https://login.yougov.com/oauth/token, with the following parameters in the request body: grant_type=authorization_code (this has a predefined value), client_id=your-client-id, code=some-auth-code, client_secret=your-client-secret

URL
https://login.yougov.com/oauth/token
HTTP methods
POST
Required parameters
grant_type - this should be fixed to a string with the value: "authorization_code".
client_id - your client ID.
code - the code value that was provided to your application in the previous step.
client_secret - your client secret.
HTTP statuses
200 - access token generated
403 - not authenticated
Response body example

{
  "access_token": "some-access-token",
  "refresh_token": "some-refresh-token",
  "scope": "brandindex",
  "token_type": "Bearer",
  "expires_in": 3600,
}

The access_token element is the most important part, which is the token your client app will need to send to the BrandIndex API endpoints to retrieve user data.

You might want to use the expires_in element as well, but it's optional, since your client app will get an HTTP 403 Unauthorized response from the BrandIndex API once the token is expired.

Time to get some user data!

The way the application will get the user data from BrandIndex API is by using the Authorization Bearer HTTP header.

Just issue a request to the BrandIndex API (say, https://api.brandindex.com/v0/company/defaults), with a header like Authorization: Bearer the-current-access-token, and the data should be retrieved just fine.

Refresh token

Now, what if the token issued has expired? You have two options:

  1. Direct the user through the OAuth2 all over again (not very friendly, but works);
  2. Request a token refresh (much more friendly, since it doesn't require intervention from the final user).

For the first option, just follow the steps from this section again.

For the second option, you may have noticed in the "Access token" section that the response has a refresh_token field. This is the code that your system will have to send back to the OAuth2 server so that it can get a refreshed access_token. Here's a complete definition of how to request it:

URL
https://login.yougov.com/oauth/token
HTTP methods
POST
Required parameters
grant_type - this should be fixed to a string with the value: "refresh_token".
client_id - your client ID.
client_secret - your client secret.
refresh_token - the refresh_token value that was provided to your application in the previous token request.
HTTP statuses
200 - refresh token generated
403 - not authenticated
Response body example

{
  "access_token": "some-access-token",
  "refresh_token": "some-refresh-token",
  "scope": "brandindex",
  "token_type": "Bearer",
  "expires_in": 3600,
}

The access_token element is the most important part, which is the token your client app will need to send to the BrandIndex API endpoints to retrieve user data.

You might want to use the expires_in element as well, but it's optional, since your client app will get an HTTP 403 Unauthorized response from the BrandIndex API once the token is expired.