Authentication


We support 3 different methods of authentication for using the BrandIndex API: OAuth 2.0 (which is the recommended), simple login and HTTP Basic Auth.

OAuth 2.0

The reason why this is the recommended method is because by using it we can ensure much more security for the users, as well as privacy over their data. With it, users login in our own pages, thus not requiring API clients to store any user password.

Configuration

Before even starting to use OAuth 2.0 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 OAuth 2.0 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-url-encoded-callback-url - notice that the "redirect_uri" parameter has to be URL-encoded!

After this step, the user will hit a login page in YouGov and, after logging in, she will be able to choose whether 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 (but URL-encoded); 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) and "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)

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) and "client_secret" (your client secret).

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/v1/analyses), 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 the OAuth 2.0 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), "refresh_token" (the refresh token value that was provided to your application in the previous token request) and "client_secret" (your client secret).

Simple Login

To use this method the API client needs to send a POST request to https://api.brandindex.com/v1/auth/login (see the "auth" section of our Swagger UI) 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. With this method, the API client acts like if it were a browser: it does a login, gets a session cookie, stores it and sends it to the server with each subsequent request.

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/v1/auth/login
  • HTTP methods: POST
  • Required parameters: "email" (the same e-mail you use to login in BrandIndex) and "password" (the same password you use to login in BrandIndex)

HTTP Basic Auth

With this method the API client can send the user credentials within the HTTP headers by using the HTTP Basic Auth standard. This method has the advantage of not requiring the client to do a preparatory login, but the disadvantage of making each request slower - since users credentials will be checked on each request.