Go To Top

Authentication via API

A guide shows how to authenticate and manage access_token using API

top_findbusinessunitid.jpg

Introduction

In this guide we’ll show you how to authenticate, refresh and revoke access_token. It consists of 3 separate API calls:

  1. Authenticate - via API (with one of supported OAuth 2.0 flows).
  2. Refresh - access_token using refresh_token.
  3. Revoke - access_token and refresh_token.

The whole process using access_token described in the following diagram:

Diagram steps description:

  1. Authentication via API - the 3rd party client authenticates. Upon successful authentication access_token and refresh_token are provided in the response.
  2. Request private resources - the 3rd party client calls private Trustpilot APIs with each request providing valid access_token.
  3. Invalid access_token - once the access_token has expired an error code will be returned. If error code indicates access_token expiration the refresh token action can be initiated.
  4. Refresh access_token - When access_token has expired the 3rd party client can call refresh endpoint to generate new access_token and refresh_token.
  5. Revoke access_token - both access_token and refresh_token are recommended to be revoked when 3rd party client has finished using Trustpilot API.

Note:

The API request in the screenshot was made using the API client application Postman.

While the API examples provided are valid, they contain sample data and {{placeholders}}. Remember to fill in the correct values for the placeholders.

Authenticate, refresh and revoke access tokens.

  1. Authenticate with OAuth 2.0 Password grant type authentication flow.

We will use OAuth 2.0 Password grant type authentication flow. This flow requires username and password during authentication process, also a valid API key & secret.

The response of this authentication flow contains access_token and refresh_token.

curl -X POST \

  https://api.trustpilot.com/v1/oauth/oauth-business-users-for-applications/accesstoken \

  -H 'Authorization: Basic {BASE64 encoded ({api_key}:{api_secret})}' \

  -H 'Content-Type: application/x-www-form-urlencoded' \

  -d 'grant_type=password&username={username}&password={password}'

The response of the authentication request is access and refresh tokens:

  • access_token - is required when calling private API endpoints. It has a short expiration time (in authentication response the expires_in property shows for how long (in seconds) the access token is valid). Usually the expiration time for access_token can vary between 1 to 4 days.
  • refresh_token - is used to obtain a renewed  access_token when the current access_token expires. The refresh_token has a much longer expiration time (It can vary, but it is usually valid for more than a 30 days).
  • expires_in - the lifetime in seconds of the access_token. When access_token expires the API requests will fail as unauthorized. To continue accessing private APIs, 3rd party client needs to use refresh_token in order to get new access_token and refresh_token.

Response:

{
   "access_token": "
{access token value}",
   "refresh_token": "
{refresh token value}",
   "expires_in": "359999"
}

Note:

  • It is recommended to authenticate only when needed and then reuse the valid access token when requesting private Trustpilot APIs. Too frequent authentication requests will be rejected with HTTP error code: 429.
  • Once the access_token has expired an HTTP error code: 401 will be returned. It is recommended to use the refresh_token to exchange it to new access_token and refresh_token.

Example of authentication via API with Postman

  1. Refresh expired access_token using a refresh_token

When access_token has expired refresh_token is used to obtain  new access_token and refresh_token. The response payload for the refresh operation is the same as in the authentication request.

curl -X POST \

  https://api.trustpilot.com/v1/oauth/oauth-business-users-for-applications/refresh \

  -H 'Authorization: Basic {BASE64 encoded({api_key}:{api_secret}}' \

  -H 'Content-Type: application/x-www-form-urlencoded' \

  -d 'grant_type=refresh_token&refresh_token={refresh_token}&client_id={api_key}&client_secret={api_secret}'

Response:

{
   "access_token": "
{access token value}",
   "refresh_token": "
{refresh token value}",
   "expires_in": "359999"
}

Refresh access_token via API with Postman example

  1. Revoke access_token and refresh_token.

After the service will no longer be using Trustpilot APIs,  both the access_token and refresh_token need to be revoked for security reasons. This is achieved with revoke request providing either access token, or refresh token values.

POST: https://api.trustpilot.com/v1/oauth/oauth-business-users-for-applications/revoke

Content-Type: “application/x-www-form-urlencoded”


Body:

token={access token or refresh token}

Example of revoke operation via API with Postman