Authorization (OAuth 2.0)

Allows third-party developers to authorize using OAuth 2.0

We use the industry-standard protocol for authorization. OAuth 2.0 provides access to our public APIs with the help of exchange of an authorization token for an access token. For detailed specification, check out the OAuth 2.0 Authorization Framework.

Here is a quick summary of the Authorization Code Flow:

After a successful setup of a developer account with KeepTruckin’s support staff, a developer can log in to the KeepTruckin’s developer portal. The developer needs to register an application on this portal. After registering your app, you will receive a client ID and a client secret. Client ID is considered public information and is used to build the login URLs. The client secret must be kept confidential.

To complete the authorization flow, you need to display a button that starts the connection process /oauth/authorize and a redirect page that would redirect the user back after connecting the application. Full URL could be like this:

https://api.keeptruckin.com/oauth/authorize?client_id=<uid of application>&redirect_uri=<redirect_uri of application>&response_type=code&scope=<all scopes mentioned in application definition>

Argument

Value

Description

Required

client_id

uid of application

The client ID you received when you first created the application

Yes

redirect_uri

Redirect URI of the application

Indicates the URI to return the user to after authorization is complete.

Yes

response_type

code

Indicates that your server expects to receive an authorization code.

Yes

scope

Scopes mentioned in the application definition:

companies.read
users.read
users.manage
vehicles.read
vehicles.manage
messages.read
messages.manage
fuel_purchases.read
fuel_purchases.manage
groups.read
groups.manage
eld_devices.read
inspection_reports.read
fault_codes.read
driver_performance_events.read
hos_logs.available_time
hos_logs.hours_of_service
hos_logs.hos_violation
hos_logs.logs
locations.vehicle_locations_list
locations.vehicle_locations_single
locations.driver_locations
ifta_reports.trips
ifta_reports.summary
utilization.driver_utilization
utilization.vehicle_utilization
utilization.idle_events
documents.read
dispatches.read
dispatches.manage
dispatch_locations.read
dispatch_locations.manage
forms.read
form_entries.read
freight_visibility_vehicle_locations.read
freight_visibility_vehicle_locations.manage
freight_visibility_asset_locations.read
freight_visibility_asset_locations.manage

One or more scope values indicating which parts of the user's account you wish to access.

Yes

After clicking the button, users are taken to a page like the one below to review the requested permissions and link to their account:

Request to authorize the application to link to KeepTruckinRequest to authorize the application to link to KeepTruckin

Request to authorize the application to link to KeepTruckin

When the user clicks on Allow, the page will be redirected to the developer's provided redirect URI. The server exchanges the auth code for an access token by hitting /token endpoint.
Note: The auth code time to live is 10 min. If the auth code is not exchanged for an access token, the auth code will expire, and the customer would need to reauthorize the app to generate a new auth code.

curl -X POST 'https://api.keeptruckin.com/oauth/token' -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=authorization_code&code=<code returned after resource owner authorization>&redirect_uri=<redirect url specified in developer app>&client_id=<uid of application>&client_secret=<secret of applicatio>'
require 'uri'
require 'net/http'
require 'json'

url = URI('https://api.keeptruckin.com/oauth/token')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/x-www-form-urlencoded'
params = {
    :grant_type    => 'authorization_code',
    :code          => '<code returned after resource owner authorization>',
    :redirect_uri  => '<redirect url specified in developer app>',
    :client_id     => '<uid of application>',
    :client_secret => '<secret of application>',
}
request.body = params.to_json

response = http.request(request)
puts response.read_body

The server replies back with an access token and expiration time.

{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "token_type": "Bearer", 
 "expires_in": 7200,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}

Once an access token is expired, the developer can simply get a new access token using the refresh token that is returned in initial response like following.

curl -X POST 'https://api.keeptruckin.com/oauth/token' -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=refresh_token&refresh_token=<refresh token returned with access token>&redirect_uri=<redirect url specified in developer app>&client_id=<uuid of application>&client_secret=<secret of applicatio>'
require 'uri'
require 'net/http'
require 'json'

url = URI('https://api.keeptruckin.com/oauth/token')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/x-www-form-urlencoded'
params = {
    :grant_type    => 'refresh_token',
    :refresh_token => '<refresh_token returned with access_token>',
    :redirect_uri  => '<redirect url specified in developer app>',
    :client_id     => '<uid of application>',
    :client_secret => '<secret of applicatio>',
}
request.body = params.to_json

response = http.request(request)
puts response.read_body

Once the OAuth access token is obtained, you can start making requests to the API. A bearer token is required to make requests.

Header Name

Value

Authorization

Bearer

Sample API call to /v1/users endpoint.

curl --request GET 'https://api.keeptruckin.com/v1/users' -H 'Authorization: Bearer <OAUTH_TOKEN>'
require 'uri'
require 'net/http'

url = URI('https://api.keeptruckin.com/v1/users')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request['Authorization'] = 'Bearer <OAUTH_TOKEN>'

response = http.request(request)
puts response.read_body
var request = require("request");

var options = { method: 'GET', url: 'https://api.keeptruckin.com/v1/users', headers: {'Authorization': 'Bearer <OAUTH_TOKEN>'} };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});