Applications connect with Traxo via OAuth 2.0 (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:

The following grant types from IETF RFC6749 are supported:

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.

Authorization Code Grant

The authorization code flow is used to authenticate a member and obtaining an access token. This is the most common flow used for web and mobile applications.

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 typically expire after 24 hours. Tokens should be protected like a password. HTTPS (TLS) transport-layer encryption is required and enforced.

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 authorization 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.

Step 4: 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" 

Refresh Token Grant

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

Client Credentials Grant

Applications may use the client_credentials grant type to generate an "app" token.

For endpoints that do not require the context of a specific member, an app token may be used.

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=client_credentials

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

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

When making requests to the API, the app token should be provided by HTTP Authorization header:

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

Client credentials can also be passed directly via HTTP headers client_id and client_secret when making requests to the API:

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

This method should be considered less secure than the app token and may be removed in the future.

Implementation Details

All API requests must be performed against https://api.traxo.com.

Authorization and token requests must be performed againsthttps://www.traxo.com.

Both require and enforce HTTPS.