Authentication overview

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.

Access public APIs

If you want to access the public API, you need to pass your API key (Client ID) for each request. You don’t need an access token. You can pass your key in as an HTTP header: apikey:{key}.

You should avoid passing your API key as a query parameter, as this can expose your API key.

Access private APIs

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.

Request an access token

To request access tokens, use the following steps:

Create a new application. You need to provide your API key (Client ID) and API secret (Client Secret). For further information, refer to Create an application.
Choose a supported Grant Type. A grant type refers to the way that the API gets your access token.
Follow the instructions for your chosen grant type below.

Grant Type	Description
Authorization code	Generate and submit an authorization code to get an access token.
Implicit	Returns an access token and expiration time.
Client Credentials	Use your domain’s API Key and Secret to request an access token.
Password (Deprecated)	Use your user’s Trustpilot username and password for authentication.

Use an access token

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

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

Authorization: Bearer <YourAccessToken>

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.

Refresh an access token

The Authorization Code and Password grant types return a refresh token with each new access 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.

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

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

There are two ways to pass your API Key and secret:

Pass your key in the the Authorization header, using HTTP Basic authentication. This is the recommended approach.
Pass your key in the payload using the client_id and client_secret parameters.

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

Revoke a refresh token

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