API Credentials

How to authenticate with the API

The RateIt API uses OAuth2 for its authentication and authorisation. To access resources, an authorisation token must be first acquired from a specific endpoint and then passed as part of the Authoization header for all subsequent requests.

Before getting started, you will need 3 important bits of information:

Client ID
Client Secret
API Key

These can all be found on the RateIt Portal on the API Credentials page under the Settings tab (only visible to Super Users). Please note that the Client Secret and API Key are both things that once generated, cannot be seen again, so make sure you store them in a safe place. You can always revoke and regenerate the secret and key, but it will make the old ones invalid. Also, all three of these items are company wide meaning they are the same for every user of the portal and if one user revokes the secret or key, it will revoke it for everyone.

Requesting an authorisation token

To receive an authorisation token, a HTTP POST request must be made to https://api.rateitapp.com/token. This request must contain an Authorization header using the Basic Authentication scheme. The Basic Authentication username and password are the Client ID and Client Secret respectively. The request body must be in the format x-www-form-urlencoded and contain the grant_type and api_key fields.

Example Request

POST /token HTTP/1.1
Host: api.rateitapp.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_ENCODED_CLIENTID_CLIENTSECRET

grant_type=api_key&api_key=API_KEY

Example Response

The response will contain the access token that is then used on subsequent requests.

{
	access_token": "ACCESS_TOKEN",
	"token_type": "bearer",
	"expires_in": 1799,
	"claims": "ClientId=CLIENT_ID, ApiKey=API_KEY, OTHER_CLAIMS",
	".issued": "Tue, 01 Jan 2018 12:00:00 GMT",
	".expires": "Tue, 01 Jan 2018 12:30:00 GMT"
}

Requesting a resource

When requesting a resource, such a list of ratings, the supplied access token should be included in the Authorization header.

GET /api/v1/your/ratings?start=2018-01-01 HTTP/1.1
Host: api.rateitapp.com
Authorization: Bearer ACCESS_TOKEN

For more information on how to interact with the API itself and to pull ratings from it, click here.

Paging results

When you are retrieving more than 1000 ratings, you will need to make multiple requests. This will hit the one request per minute limit however. To get around this, in the first successful response, it will include a continuationToken. This will need to be included in the next request as a URL parameter where the key is the words continuationToken and the value is the value from the first response. Please note that you will also need to increase the skip URL parameter to 1000 (to skip the first 1000 ratings and get the next 1000). For more information about the URL parameters, click here.