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.
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.
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.
With this flow your application will be able to get an access token to use when retrieving protected user data.
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.
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"
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.
Now, what if the token issued has expired? You have two options:
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:
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.
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.