Go To Top

Authentication

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. First, you need to obtain an API key (Client Id) and API secret (Client Secret) from your Trustpilot account manager.

 

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

 

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

OAuth2 flow

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 AND 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 Base64EncodedAPIkeyAndAPISecret

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 AND 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 AND 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

Headers:

Authorization: Basic [BASE64 ENCODED API Key AND 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 Base64EncodedClientIdAndClientSecret

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".