Skip to main content

Authentication

Maps to: auth

Except for the health check and the login endpoint itself, every request must be authenticated. The BrandIndex API supports three methods:

MethodBest forTrade-off
OAuth 2.0Interactive apps (e.g. a third-party dashboard)Users log in via YouGov's screen; the client never stores passwords. Setup requires a client ID/secret.
Simple loginAutomated apps (e.g. a script)One login call, then reuse the session cookie.
HTTP Basic AuthQuick/one-off callsNo preparatory login, but credentials are checked on every request, making each one slower.

BrandIndex recommends OAuth for interactive applications and simple login for automated ones.

OAuth 2.0​

Greater security and privacy: users authenticate on YouGov's own login screen, so your application never handles their passwords.

Setup: contact YouGov to obtain a client ID and client secret for the OAuth flow.

1. Send the user to authorize​

Redirect the user to:

https://login.yougov.com/oauth/authorize
  ?response_type=code
  &scope=brandindex
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_URL_ENCODED_CALLBACK

Important: redirect_uri must be URL-encoded.

The user logs in and grants access, then BrandIndex redirects to your redirect_uri with a code query parameter appended — e.g. https://example.com/my-app/callback?code=some-auth-code.

2. Exchange the code for an access token​

POST https://login.yougov.com/oauth/token

Required parameters: client_id, client_secret, code (from step 1), grant_type=authorization_code.

The response includes an access token and a refresh token.

3. Call the API​

Send the access token as a bearer header:

Authorization: Bearer THE_ACCESS_TOKEN

e.g. GET https://api.brandindex.com/v1/analyses.

4. Refresh an expired token​

Rather than sending the user through login again, POST to the token endpoint with the refresh_token:

POST https://login.yougov.com/oauth/token

Required parameters: client_id, client_secret, grant_type=refresh_token, refresh_token (from the previous token response).

Simple login​

Behaves like a browser: log in once, receive a session cookie, and send it with every subsequent request.

POST https://api.brandindex.com/v1/auth/login
{
  "meta": { "version": "v1" },
  "data": { "email": "you@example.com", "password": "••••••••" }
}

Store the response cookies and include them on all subsequent requests — every protected endpoint requires the logged-in session. (Request bodies follow the standard envelope format.)

Failed logins return 404, not 401: a wrong password or an unknown email both return 404 with the message User "<email>" not found. Handle 404 (not just 401) when scripting the login call.

If your account has been disabled for abuse, login returns 401 with an explanatory message — contact your YouGov representative.

HTTP Basic Auth​

Send the user's credentials in the HTTP Authorization header on each request, per the HTTP Basic Auth standard. No preparatory login is needed, but because credentials are validated on every call, each request is slower.

Entitlements​

Whichever method you use, results only ever include the regions, sectors, brands and metrics your account is licensed for. Requesting something outside your entitlements returns an authorization error.

Common failures​

StatusMeaning
401Not authenticated on a protected endpoint — missing, invalid or expired session, token or Basic credentials — or an account disabled for abuse.
403Authenticated, but not entitled to the requested resource.
404On POST /v1/auth/login only: wrong password or unknown email (User "<email>" not found).