TruckDown

API

Table of Contents

API Documentation

Overview

The TruckDown.com API provides access to TruckDown.com services and features through a standard REST application interface. Using the API, external applications can perform location searches, view user information and preference data, and view and manage user specific ratings, notes, preferences, and repair data.

The TruckDown.com API supports OAuth 2.0 authentication for web applications (see OAuth 2.0 for Web Applications) or for applications or devices that have limited input capabilities (see OAuth 2.0 for Devices).

This document outlines the various methods to authenticate to the TruckDown.com API and defines the API available.

Obtaining a TruckDown Application API Key and Secret

Like all OAuth 2.0 scenarios, you first need to register your application with TruckDown through your account services at https://www.truckdown.com/account/services. In order to register your application, you must log in to www.truckdown.com and have a TruckDown Ace Membership. For more information on TruckDown Ace Membership benefits, click here.

To register your application, click on the “Services” section. Under “API Applications”, click on the “Add new API application” link. You will be asked to enter a name for your application, a status (Private, Semi-Private, or Public), and you can optionally enter a Url End Point. (Note: the Url End Point is required for OAuth 2.0 for Web Applications – this is the Url that TruckDown will redirect users to after they have granted access to your application).

The statuses have the following meanings:

  1. Public – Applications with a Public status can be searched and the name along with your company name can be viewed by all users of TruckDown.com. Users can store their own basic authentication password for your application.
  2. Private – Applications with a Private status cannot be viewed or searched by users of TruckDown. This status is only not applicable to OAuth 2.0 authentication. Basic authentication is not supported for Private applications.
  3. Semi-Private – Applications with a Semi-Private status can only be viewed or searched by users of your company account. Only your users can enter their own basic authentication password.

Once you have saved your application, your application will be listed in your API Applications list along with an API Key and an API Secret. The API Key can be shared but the API Secret should be kept secret within your application.

OAuth 2.0 for Web Applications

Overview

In order to authenticate a user within a web application, you application can redirect the user’s browser to a TruckDown URL with a set of query parameters that indicates the type of access TruckDown API access the application requires. TruckDown handles the user authentication and consent, and returns an authorization code to your application through another URL redirect.

Your application can then use that authorization code to obtain an Access Token and a Refresh Token. The Access Token is a time limited token that can be used to grant your application access to the TruckDown API on the user’s behalf while the refresh token can be used to renew the access token as required.

Requesting Access

The URL used when authenticating a user is https://www.truckdown.com/oauth2/auth. The endpoint is only accessible over SSL, any connection attempt over HTTP will be refused.

The query string parameters to include in the request are:

Parameter:
api_key
Values:
The API KEY obtained from your Account Services
Description:
Indicates the application that is making the request. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
redirect_url
Values:
The registered URl End Point for your application
Description:
This value determined where the user is redirected to after they either authorize your application or decline it. This value must exactly match the Url End Point configured for your application.
Parameter:
scope
Values:
A space delimited set of permissions the application requests
Description:
Indicates the TruckDown API access your application is requesting. See Scope Values for possible values.
Parameter:
state
Values:
Any string
Description:
Indicates any state that may be useful to your application upon receipt of the response. TruckDown will round trip this parameter so that your application receives the same value that is sent.

An example request url is shown below:

https://www.truckdown.com/oauth2/auth?api_key=Uj8DVqeQGQi8yaVp&redirect_url=https%3a%2f%2fapitest.truckdown.com%2fhome%2fextauth&scope=Account+Search&state=test_for_api

When the user is directed to the request url, they will be asked to log in to TruckDown if they are not already and then will be shown a consent screen.

Once the user clicks on either button, they will be redirected back to the redirect_url with the appropriate response.

Handling the Access Response

The response will be sent to the redirect_url as specified in the request. If the user approves the access request, then the response contains the state parameter and an authorization code. If the user does not approve the request then the response contains the state parameter and an error message.

For example:

An error response:

https://apitest.truckdown.com/home/extauth?state=test_for_api&error=access_denied

An Authorization Code response:

https://apitest.truckdown.com/home/extauth?state=test_for_api&code=/JMhqlAq

Obtaining an Authentication Token

After the web server receives the authorization code, it may exchange the authorization code for an access token and a refresh token.

The request for an access token is an HTTPS POST to

https://www.truckdown.com/apiv2/oauth2/token?key=[api_key]

with the following parameters:

Parameter:
api_key
Description:
Indicates the application that is making the request. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
api_secret
Description:
The API Secret. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
token
Description:
The authorization code returned form the initial request.
Parameter:
grant_type
Description:
As defined in the OAuth2.0 specification, the field must contain the value authorization_code

NOTE: the api_key must be sent as both a query string parameter (key) and in the POST parameter (api_key). If the query string parameter is omitted or invalid then TruckDown will return an Unauthorized response (401).

A successful response is returned as a JSON object with the following fields:

Parameter:
access_token
Description:
The token that can be sent to a TruckDown API
Parameter:
refresh_token
Description:
A token that can be used to obtain a new access token. Refresh tokens are valid until the user revokes access.
Parameter:
expires_in
Description:
The remaining number of seconds that the access_token is valid for.
Parameter:
token_type
Description:
Indicates the type of token returned. This field will always have the value Bearer.

An example response object would be similar to:

                    
{
    access_token: “WVPnLc3CcpQjguyJMYucsOSJ5wOe/G5q”,
    refresh_token: “TSdph4Z14Lmo9CFa8ovIxe4/84R5jtcjtcYcl1wr6fDmbPgU+HuvqMs7BNV/a0sn”,
    expires_in: 3600,
    token_type: “Bearer”
}

Additional fields may be returned in the response so your application should allow additional fields.

Note: It is important to store the refresh token for future use. If you application loses the refresh token, it will have to obtain a new one through the initial authorization request process.

Calling the TruckDown API

After your application has obtained an access token, your application can access a TruckDown API by including it in an Authorization: Bearer HTTP header.

For example, a call to the TruckDown API to get the user’s basic information looks like the following:
GET /api/user HTTP/1.1
Authorization: Bearer WVPnLc3CcpQjguyJMYucsOSJ5wOe/G5q
Host: www.truckdown.com

Using the Refresh Token

When you obtain an access_token, that token will expire after a set number of seconds (as defined by the expires_in parameter). Prior to the access_token expiring, you can use the refresh_token value to obtain a new access_token to ensure continued access.

The request for a new access token is an HTTPS POST to https://www.truckdown.com/apiv2/oauth2/token?key=[api_key] with the following parameters:
Parameter:
api_key
Description:
Indicates the application that is making the request. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
api_secret
Description:
The API Secret. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
token
Description:
A valid refresh token.
Parameter:
grant_type
Description:
As defined in the OAuth2.0 specification, the field must contain the value refresh_token

NOTE: the api_key must be sent as both a query string parameter (key) and in the POST parameter (api_key). If the query string parameter is omitted or invalid then TruckDown will return an Unauthorized response (401).

A successful response is returned as a JSON object with the following fields:

Parameter:
access_token
Description:
The token that can be sent to a TruckDown API
Parameter:
refresh_token
Description:
A token that can be used to obtain a new access token. Refresh tokens are valid until the user revokes access.
Parameter:
expires_in
Description:
The remaining number of seconds that the access_token is valid for.
Parameter:
token_type
Description:
Indicates the type of token returned. This field will always have the value Bearer.

An example response object would be similar to:

                    
{
    access_token: “WVPnLc3CcpQjguyJMYucsOSJ5wOe/G5q”,
    refresh_token: “TSdph4Z14Lmo9CFa8ovIxe4/84R5jtcjtcYcl1wr6fDmbPgU+HuvqMs7BNV/a0sn”,
    expires_in: 3600,
    token_type: “Bearer”
}

Additional fields may be returned in the response so your application should allow additional fields. The value of the refresh_token field will be the same as the value submitted.

OAuth 2.0 for Devices

Overview

Applications that do not have the same capabilities as a web server (such as GPS devices) may access an API on behalf of a user, but the user must have separate access to a computer or device with an integrated web browser. The user will interact with the device to obtain an URL and a code, switch to another device or computer to launch a web browser, navigate to the URL and authenticate the code provided.

Obtaining a User Code

In order to obtain a user code for authorization, you application must make an HTTP POST Request to https://www.truckdown.com/apiv2/oauth2/code?key=[api_key]. The endpoint is only accessible over SSL, any connection attempt over HTTP will be refused.

The fields to include in the request are:

Parameter:
api_key
Values:
The API Key obtained from your Account Profile
Description:
Indicates the application that is making the request. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
api_secret
Values:
The API Secret obtained from your Account Services.
Description:
This value determined where the user is redirected to after they either authorize your application or decline it. This value must exactly match the Url End Point configured for your application.
Parameter:
scope
Values:
A space delimited set of permissions the application requests
Description:
Indicates the TruckDown API access your application is requesting. See Scope Values for possible values.

NOTE: the api_key must be sent as both a query string parameter (key) and in the POST parameter (api_key). If the query string parameter is omitted or invalid then TruckDown will return an Unauthorized response (401).

A successful response is returned as a JSON object with the following fields:

Parameter:
verification_url
Description:
The URL that the user can go to to submit the user_code and grant access to the application.
Parameter:
device_code
Description:
A device code for the application to be used when obtaining an access token.
Parameter:
user_code
Description:
The User Code that the user must submit to the verification_url in order to grant access to the application.
Parameter:
expires_in
Description:
The remaining number of seconds that the user_code is valid for.
Parameter:
interval
Description:
The minimum number of seconds allowed between requests for the access_token. This can be used is your application polls TruckDown to obtain authorization.

An example response object would be similar to: 

                    
{
    verification_url: “https://www.truckdown.com/code”,
    device_code: "kuFIyJbY1fE2Peq4rt8A1/xlrGnS+zmz/3Bkq03PI4gMBaUTfdBYJGI1kl9/Q/dC",
    refresh_token: "m78CHQEj",
    expires_in: 3600,
    interval: 5
}

Additional fields may be returned in the response so your application should allow additional fields.

The verification_url and the user_code from the JSON object should be shown to your user. The idea is to ask your user to go to a browser, navigate to the verification_url, and enter the user_code. The user_code is case sensitive so the user will have to enter it exactly as it is returned in the JSON object.

When a user navigates to the URL, they will be asked to log in (if they are not already logged in) and then will see a page similar to the following:

After they enter the code, they will be shown a consent screen.

If the user clicks “Allow Access”, then your application can obtain an access and refresh token that will grant your application access to the TruckDown APIs. Like all OAuth 2.0 scenarios, the scope parameter controls the access your application has to a TruckDown API.

Obtaining an Authentication Token

After your application has shown the user_code and verification_url, your application may begin polling a TruckDown end point with the device_code that was returned in your last request.

The request for an access token is an HTTPS POST to https://www.truckdown.com/apiv2/oauth2/token?key=[api_key] with the following parameters:

Parameter:
api_key
Description:
Indicates the application that is making the request. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
api_secret
Description:
The device code returned from the initial request.
Parameter:
token
Description:
The User Code that the user must submit to the verification_url in order to grant access to the application.
Parameter:
grant_type
Description:
As defined in the OAuth2.0 specification, the field must contain the value device_code

NOTE: the api_key must be sent as both a query string parameter (key) and in the POST parameter (api_key). If the query string parameter is omitted or invalid then TruckDown will return an Unauthorized response (401).

A successful response is returned as a JSON object with the following fields:

Parameter:
access_token
Description:
The token that can be sent to a TruckDown API
Parameter:
refresh_token
Description:
A token that can be used to obtain a new access token. Refresh tokens are valid until the user revokes access.
Parameter:
expires_in
Description:
The remaining number of seconds that the access_token is valid for.
Parameter:
token_type
Description:
Indicates the type of token returned. This field will always have the value Bearer.

An example response object would be similar to:

                    
{
    access_token: “WVPnLc3CcpQjguyJMYucsOSJ5wOe/G5q”,
    refresh_token: “TSdph4Z14Lmo9CFa8ovIxe4/84R5jtcjtcYcl1wr6fDmbPgU+HuvqMs7BNV/a0sn”,
    expires_in: 3600,
    token_type: “Bearer”
}

Additional fields may be returned in the response so your application should allow additional fields.

Note: It is important to store the refresh token for future use. If you application loses the refresh token, it will have to obtain a new one through the initial authorization request process.

Calling The TruckDown.com API

After your application has obtained an access token, your application can access a TruckDown API by including it in an Authorization: Bearer HTTP header.

For example, a call to the TruckDown API to get the user’s basic information looks like the following:

GET /api/user HTTP/1.1
Authorization: Bearer WVPnLc3CcpQjguyJMYucsOSJ5wOe/G5q
Host: www.truckdown.com

Using The Refresh Token

When you obtain an access_token, that token will expire after a set number of seconds (as defined by the expires_in parameter). Prior to the access_token expiring, you can use the refresh_token value to obtain a new access_token to ensure continued access.

The request for a new access token is an HTTPS POST to https://www.truckdown.com/apiv2/oauth2/token?key=[api_key] with the following parameters:

Parameter:
api_key
Description:
Indicates the application that is making the request. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
api_secret
Description:
The API Secret. The value passed in this parameter must exactly match the value shown in your Account Services.
Parameter:
token
Description:
A valid refresh token.
Parameter:
grant_type
Description:
As defined in the OAuth2.0 specification, the field must contain the value refresh_token

NOTE: the api_key must be sent as both a query string parameter (key) and in the POST parameter (api_key). If the query string parameter is omitted or invalid then TruckDown will return an Unauthorized response (401).

A successful response is returned as a JSON object with the following fields:

Parameter:
access_token
Description:
The token that can be sent to a TruckDown API
Parameter:
refresh_token
Description:
A token that can be used to obtain a new access token. Refresh tokens are valid until the user revokes access.
Parameter:
expires_in
Description:
The remaining number of seconds that the access_token is valid for.
Parameter:
token_type
Description:
Indicates the type of token returned. This field will always have the value Bearer.

An example response object would be similar to: 

                    
{
    access_token: “WVPnLc3CcpQjguyJMYucsOSJ5wOe/G5q”,
    refresh_token: “TSdph4Z14Lmo9CFa8ovIxe4/84R5jtcjtcYcl1wr6fDmbPgU+HuvqMs7BNV/a0sn”,
    expires_in: 3600,
    token_type: “Bearer”
}

Additional fields may be returned in the response so your application should allow additional fields. The value of the refresh_token field will be the same as the value submitted.

Scope Values

The list of possible Scope values will change over time as new API features are added or enhanced. The current list included:

Scope:
Account
Description:
Account information including name, e-mail address, phone number, and preferences
Scope:
Search
Description:
TruckDown Search preferences including notes, repairs, preferred vendors, and ratings

Notes On API Authorization

At any point in time, a user can revoke access to your application through their Account Services on TruckDown.com. If this occurs, then any Access Tokens or Refresh Tokens you have will be refused and any API requests made will return an Unauthorized (401) response.

If your access has been revoked, the only option is to have the user grant access again through one of the mechanisms outlined previously.