Customer APIs contain private resources and use OAuth 2.0 authentication. In order to access private resources, you need an access token. This document describes how to obtain, refresh and revoke your access token. In order to create an access token, firstly you need to create a new application with API key (Client Id) and API secret (Client Secret). You can do that by following this guide.

 

Then follow the OAuth2 flow described below. We suggest you use an auth client to execute the OAuth2 authentication flow. You'll find auth clients in several languages here: oauth.net/2/#client-libraries

Note

 

We support the following Grant Types in OAuth2 flow:
Grant Type: Password
Grant Type: Authorization Code
Grant Type: Implicit
Grant Type: Client Credentials

The "password" grant type can only be used from server side to avoid exposing your API Secret and credentials. Using this grant type allows you to obtain both an access token and a refresh token. It involves the following steps:

1. Request an access token

To obtain a token you need your API Key, API Secret, Trustpilot username and password.

Method: POST

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

Headers:

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]
Content-Type: application/x-www-form-urlencoded

The KEY AND SECRET needs to be concatenated as follows KEY:SECRET and then base64 encoded

Payload:

Name	Type	Description
grant_type	Required string	Value must be set to password
username	Required string	Your Trustpilot b2b login email
password	Required string	Your Trustpilot b2b login password

Example:

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

Header:

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]

Payload:

grant_type=password&username=email@domain.com&password=Password

The response will contain amongst other fields the access token, refresh token and time of expiration:

{ access_token: "AccessToken",
refresh_token: "RefreshToken",
expires_in: "359999" }

Once the access token expires, issue the same request to obtain a new token or use the refresh token obtained in the response.

The authorization code grant type is the most commonly used grant type for server-side applications. Using this grant type allows you to obtain both an access token and a refresh token. It involves the following steps:

1. Redirect to Trustpilot website for Authorization

The user is redirected to a website owned by Trustpilot in order to be authorized. After the authorization succeeds, Trustpilot redirects the user back to the client site with a code parameter containing the authorization code.

Method: GET

https://authenticate.trustpilot.com

Parameters:

Name	Type	Description
client_id	Required string	The API key
redirect_uri	Required string	The client's site URL. The URL in your app where it will be redirected to after authorization. You need to specify the redirect_uri while getting the API key from account manager. The redirect_uri must be https.
response_type	Required string	Value must be set to code

Example:

https://authenticate.trustpilot.com?client_id=APIKey&redirect_uri=https://www.clientsSite.com&response_type=code

Redirects back to: https://www.clientsSite.com/?code=Code

2. Request an access token

Use the authorization code obtained in the previous step to obtain an access token via the following request:

Method: POST

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

Headers:

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]
Content-Type: application/x-www-form-urlencoded

Payload:

Name	Type	Description
grant_type	Required string	Value must be set to authorization_code
code	Required string	The provided code after the redirection
redirect_uri	Required string	The client's site URL. The URL in your app where it was redirected to after authorization. It has to be identical to the redirect_uri parameter provided in the first step of authorization. The redirect_uri must be https.
client_id	Optional string	The API key
client_secret	Optional string	The API secret

Example:

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

Header:

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]

The API key and secret can be passed either in Authorization header, using HTTP Basic authentication, or in payload, using the client_id and client_secret parameters. Using HTTP Basic authentication is the recommended approach.

Payload:

grant_type=authorization_code&code=Code&redirect_uri=https://www.clientsSite.com

The response will contain amongst other fields the access token and the refresh token:

{ access_token: "AccessToken",
refresh_token: "RefreshToken",
expires_in: "359999" }

The Implicit grant type is used only for pure browser-based applications. The user will obtain only an access token. It involves the following steps:

1. Redirects to Trustpilot website for Authorization

The user is first redirected to a website owned by Trustpilot in order to be authorized. After the authorization succeeds, Trustpilot redirects the user back to the client site with an access_token parameter that contains the access token to access the Trustpilot API and an expires_in parameter that specifies when the access token expires:

Method: GET

https://authenticate.trustpilot.com

Parameters:

Name	Type	Description
client_id	Required string	The API key
redirect_uri	Required string	The client's site URL. The URL in your app where it will be redirected to after authorization. The redirect_uri must be https.
response_type	Required string	Value must be set to token

Example:

https://authenticate.trustpilot.com?client_id=APIKey&redirect_uri=https://www.clientsSite.com&response_type=token

Redirects back to:

https://www.clientsSite.com/#access_token=AccessToken&token_type=bearer&expires_in=359999

Notice that the access_token parameter is available behind the fragment, and thus available to client side scripting.

Refresh the Access Token

Every access token has an expiration date. When the access token expires, the user needs a refresh token to generate a new access token. Note that the user can obtain a refresh token using both the Authorization Code grant type and the Password grant type as described above.

Use the following request to receive a new access token:

Method: POST

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

or

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

Headers:

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]
Content-Type: application/x-www-form-urlencoded

The API key and secret can be passed either in Authorization header, using HTTP Basic authentication, or in payload, using the client_id and client_secret parameters. Using HTTP Basic authentication is the recommended approach.

Payload:

Name	Type	Description
grant_type	Required string	Value must be set to refresh_token
refresh_token	Required string	The refresh token
client_id	Optional string	The API key
client_secret	Optional string	The API secret

Example:

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

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]

Payload:

grant_type=refresh_token&refresh_token=RefreshToken

The response will contain amongst other fields the access token and the refresh token:

{ access_token: "AccessToken", refresh_token: "RefreshToken" }

Revoke the Refresh Token

The user has the option to revoke a refresh token. Note that revoking a refresh token also revokes the related access token.

Use the following request to revoke a refresh token:

Method: POST

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

Headers:

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

Payload:

Name	Type	Description
token	Required string	The refresh token

Example:

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

Payload:

token=7Xu4MQ9xsvUA0Tard2bIofnLjacrw7RL

The user receives a 200 response if the revocation succeeded.

Using the Access Token

With the access token you are ready to call any of the Customer APIs.
To call any of the Customer API endpoints you need to pass along the access token. It can be passed either as a header or in the querystring.
For example if you pass in the query string, the URL is as follows:

https://api.trustpilot.com/v1/private/business-units/[YOUR BUSINESS UNIT ID]/reviews?token=[YOUR ACCESS TOKEN]

You may pass it as a header as follows:

Authorization: Bearer YourAccessToken

Note that in the JSON returned the property is called "access_token" but when passing into the next API the parameter should be called "token".

The "client_credentials" grant type can only be used from server side to avoid exposing your API Secret. Using this grant type allows you to obtain an access token.
Note that when using this grant type the access token is not scoped to a user, therefore some endpoints will require user's id to be provided in form of a header (usually x-business-user-id) or in the request body.
User's id can be obtained in the user's profile page.
Obtaining an access token involves the following steps:

1. Request an access token

To obtain a token you need your API Key, API Secret.

Method: POST

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

Headers:

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]
Content-Type: application/x-www-form-urlencoded

The API_KEY and API_SECRET needs to be concatenated as follows API_KEY:API_SECRET and then base64 encoded

Payload:

Name	Type	Description
grant_type	Required string	Value must be set to client_credentials

Example:

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

Header:

Authorization: Basic [BASE64_ENCODED(API_KEY:API_SECRET)]

Payload:

grant_type=client_credentials

The response will contain amongst other fields the access token and time of expiration:

{ access_token: "AccessToken", expires_in: "359999" }

Once the access token expires, issue the same request to obtain a new token.