Last updated 6 minutes ago

Authorization

Each request to the New Routehappy API requires two authorization strings: an API Key, and an Access Token. This is unlike the legacy Routehappy Scores & Amenities (S&A) and Hub APIs, which required only an API Key.

Field New Routehappy API Legacy Routehappy APIs
API Key required in header parameter, x-api-key required in header parameter, Auth
Access Token required in header parameter, Authorization,
prepended with the token_type followed by a space
none

Note that the header parameter name for API Key has changed: it is now x-api-key.

Authorization Example

The following example shows how to include both your API Key and an active Access Token in a curl request.

Let's assume:

  • API Key is ABCDefghIJKL0123456789mnopQRSTuvwxYZ0123
  • Access Token is *********_an_access_token_*********
  • token_type is Bearer

Then a curl request would include:

--header 'x-api-key: ABCDefghIJKL0123456789mnopQRSTuvwxYZ0123' \
--header 'Authorization: Bearer *********_an_access_token_*********'

API Key

Each request to the New Routehappy API requires an API Key. ATPCO provided you with an API Key when you registered for the New Routehappy API. Your API Key must be provided as the x-api-key value in your request header.

For example, if your API Key is ABCDefghIJKL0123456789mnopQRSTuvwxYZ0123, you would include your API Key in a curl request with the following code:

--header 'x-api-key: ABCDefghIJKL0123456789mnopQRSTuvwxYZ0123'

Access Token

Each request to the New Routehappy API requires a valid Access Token. ATPCO Access Tokens typically expire after one hour, so you will need to obtain a new token at most once per hour. Once you obtain a valid Access Token, you will need to include it in your request header.

Obtain an Access Token

You'll need three pieces of information to obtain an Access Token:

  1. Your client_id
  2. Your client_secret
  3. The Access Token URL

You should have received each of these items from ATPCO when you registered for the New Routehappy API.

You'll submit an API request to the Access Token URL, which will return a valid Access Token.

The following example shows how to request an Access Token using curl. Assume your client_id is ****, your client_secret is ****, and the Access Token URL is https://access.token.url/.

requestresponse
curl --location --request POST 'https://access.token.url/' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
	 --data-urlencode 'client_id=****' \
	 --data-urlencode 'client_secret=****' \
	 --data-urlencode 'grant_type=client_credentials'
{​​​​​
	"access_token": "*********_an_access_token_*********",
	"token_type": "Bearer",
	"expires_in": 3600,
	"scope": "resource.WRITE resource.READ"
}​​​​​

You will use the value returned in the access_token field in your New Routehappy API request.

Include an Access Token in the header

Your token_type and Access Token must be provided as the Authorization value in your request header, separated by a space.

For example, if your token_type is Bearer and your Access Token is *********_an_access_token_*********, you would include them in a curl request with the following code:

--header 'Authorization: Bearer *********_an_access_token_*********'