Applications connect with Traxo via OAuth 2.0. This is the standard used by most major API providers, including the Facebook Graph API and Foursquare.

The OAuth 2.0 Authorization Protocol - IETF RFC6749

The Traxo Authorization Server currently implements Draft 20 of the OAuth 2.0 specification with the following enhancements or inclusions from later drafts:

Registration

Start by registering your application to obtain API credentials. Each set of credentials is tied to a particular URL, so you may want to create different applications for your development and production environments. Multiple applications can be created within the same developer account. Protect your client_secret like a password and take steps to obfuscate it if you include it in released code. Be prepared to rotate your client_secret if needed.

Access Tokens

Access tokens allow applications to issue API requests on behalf of a Traxo member. Each access token is tied to the member and the application uniquely. Access tokens expire after 24 hours. Protect access tokens like a password. HTTPS (SSL) transport-layer encryption is required and enforced. Currently, the "code" flow is supported for authenticating a member and obtaining an access token. This is the most common flow used for web and mobile applications.

Step 1: Redirect

Redirect users who wish to authenticate to:

https://www.traxo.com/oauth/authenticate?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&state=YOUR_CRSF_STATE_PARAMETER

If the member authorizes your application, they will be redirected back to your registered redirect url with the "code" parameter appended (shown as $CODE below)

https://YOUR_REGISTERED_REDIRECT_URI/?state=YOUR_CRSF_STATE_PARAMETER&code=$CODE

If the member does not authorize your application, they will be redirected back to your registered redirect url with additional parameters: "error" and "error_description"

https://YOUR_REGISTERED_REDIRECT_URI/?state=YOUR_CRSF_STATE_PARAMETER&error=access_denied&error_description=...

Step 2: Exchange the code

Exchange the code ($CODE) obtained in the previous step for an access_token.

Your server should make a HTTP POST request to the token endpoint of the authorization server:

https://www.traxo.com/oauth/token

Headers:
Content-type: application/x-www-form-urlencoded
POST body parameters:
client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code=$CODE

The authorization code is valid for 1 minute, so ensure that your server time is correct and the request is made as soon as possible.

The Traxo authorization server will respond with a json object:

{
   "access_token": "1df5fd433605903257e556a38f77471f37072535",
     "expires_in": 86400,
     "token_type": "bearer",
          "scope": "",
  "refresh_token": "cbbc382e8adadc076f74d4c8f1bac97c4f1fce8e"
}

Step 3: Store tokens

Store the access_token and refresh_token in your database associated with the user account that originated the request.

Refreshing an Access Token

Section 6 of the specification provides a simple process by which a client can retrieve a new access token without requiring the user to reauthorize the client. Refresh tokens expire 1 year after issue.

Using a refresh_token saved from Step 2 of the "code" flow above, your server should make an HTTP POST request to the /oauth/token endpoint of the authorization server:

https://www.traxo.com/oauth/token

Headers:
Content-type: application/x-www-form-urlencoded
POST body parameters:
client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=A_VALID_REFRESH_TOKEN

The authorization server will respond with a json object containing a new access_token and refresh_token that should be stored in your database and associated with the same user account.

{
  "access_token": "5fdd663189220a2a811f6f6ff5fb1197782a7b41",
  "expires_in": 86400,
  "token_type": "bearer",
  "scope": "",
  "refresh_token": "9b977f241186ab7786ca67019bed1b06bda23687"
}

Making Requests

Most endpoints require an access token to make requests on behalf of a particular Traxo member. The API conforms to the OAuth 2.0 Bearer Token specification (RFC6750) when accessing protected resources.

The access token should be provided by HTTP Authorization header:

curl -v -H "Authorization:Bearer {ACCESS_TOKEN}" -X GET "https://api.traxo.com/v2/me" 

For endpoints that require client credentials, those credentials should be passed via HTTP headers client_id and client_secret.

curl -v -H "client_id:{CLIENT_ID}" -H "client_secret:{CLIENT_SECRET}" -X GET "https://api.traxo.com/v2/locations/airports?q=DFW" 

All API requests must be performed against https://api.traxo.com. Authorization and token requests must be performed against https://www.traxo.com. Both require and enforce HTTPS.