Authentication

Trustpilot offers public and private APIs. You can access public APIs with only your API key (Client ID) but if you want to access private APIs you need to use OAuth 2.0 authentication.

OAuth 2.0 uses access and refresh tokens to authenticate your access to private APIs. Access tokens expire after 100 hours and refresh tokens expire after 30 days. When your current access token expires, you can use your refresh token to request a new access token. To check how long your access has until expiration, use expires_in.

You should wait until your current access token expires before you request a new one. If you refresh your access token too often, your requests will be rejected with HTTP error code: 429.

It is recommended that you use an auth client to execute your chosen OAuth 2.0 authentication flow. For further information about auth clients, refer to OAuth.net.

Note: OAuth authentication is not supported for users with two-factor authentication enabled. If you use the Password, Authorization Code or Implicit grant type, you must instruct your users to turn-off two-factor authentication when they log in.

To request access tokens, use the following steps:

1. Create a new application with your API key (Client ID) and API secret (Client Secret). For further information, refer to How to use Trustpilot APIs.
2. Choose a supported Grant Type. A grant type refers to the way that the API gets your access token.
3. Follow the instructions for your chosen grant type below.

Grant Type: Password
Grant Type: Authorization Code
Grant Type: Implicit
Grant Type: Client Credentials

The Password grant type enables you to use your user's Trustpilot username and password for authentication. You can only use this grant type from server side to avoid exposing your API Secret and user credentials.

Request an access token

To request a token, use 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

You must concatenate and base64 encode your API Key and API Secret.

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

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

Response

The response contains the access token, refresh token and time of expiration:

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

When the access token expires, issue the same request to get a new token. You can also use the refresh token from the response.

The Authorization Code grant type generates and submits an authorization code to get an access token. In most cases, you should avoid using this grant type for automation as it requires your user to log in to get the authorization code. To get an authorization code and request an access token, use the following steps:

1. Get an authorization code

During the log in process, the Authorization Code grant type redirects your user to a Trustpilot owned website where they are authenticated and return with a parameter containing an authorization code. You must use the returned authorization code to request an access token (step 2).

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 you want to be redirected after authorization. When you get the API key from your account manager, you need to specify the redirect_uri. 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 that you got in the previous step to request an access token.

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

You can pass your API Key and Secret in either the Authorization header, using HTTP Basic authentication, or in the payload, using the client_id and client_secret parameters. It is recommended to use the HTTP Basic authentication approach.

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

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

Response

The response contains the access token, refresh token and time of expiration:

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

When your access token expires, your user needs to log in to get a new authorization code.

Use the the Implicit grant type for pure browser-based applications. This grant type only returns an access token and expiration time. In most cases, you should avoid using the Implicit grant type for automation as it requires your user to log in to get an access token.

Request an access token

During the log in process, the Implicit grant type redirects your user to a Trustpilot owned website where they are authenticated and return with a parameter containing an access token and expiration time.

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 you want your user to 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

The access_token parameter is stored behind the fragment and is available to client side scripting.

The Client Credentials grant type uses your domain's API Key and Secret to request an access token. You can only use this grant type from server-side to avoid exposing your API secret.

Note: If you use this grant type, the access token won't be assigned to a specific user. To use endpoints that require a user's ID, complete the following steps:

1. Go to the user's Trustpilot Business profile page.
2. Copy the User ID.
3. Provide the User ID as a header or in the request body.

Request an access token

To get an access 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

You must concatenate and base64 encode your API Key and API Secret.

Payload

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

Example

grant_type=client_credentials

Response

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

When the access token expires, issue the same request to get a new token.

Access tokens expire after 100 hours and refresh tokens expire after 30 days. When your access token expires, you can use the refresh token to generate a new access token. The Authorization Code and Password grant types return a refresh token with each new access token.

Use one of the following requests 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

You can pass your API Key and Secret in either the Authorization header, using HTTP Basic authentication, or in the payload, using the client_id and client_secret parameters. It is recommended to use the HTTP Basic authentication 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

grant_type=refresh_token&refresh_token=RefreshToken

Response

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

You can revoke a refresh token. 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

token=7Xu4MQ9xsvUA0Tard2bIofnLjacrw7RL

Response

You receive a 200 response if the revocation succeeds.

If you want to use any of the private APIs, you need to use an access token. You can pass along an access token as a header or in the query string.

To pass an access token in the query string, use the following example URL:

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

Note: The returned JSON refers to the property as access_token, but when you pass it into the next API you need to call it token.

To pass an access token as a header, use the following example header:

Authorization: Bearer YourAccessToken