API

How to get started

Once we have setup your API account, you can login to API store to get your secret API credentials. You can exchange these credentials for an access token that authorizes your API calls.

Setup application

An application is a logical collection of APIs. Applications allow you to use a single access token to invoke a collection of APIs and to subscribe to one API multiple times with different SLA levels.

To setup a new application:

  1. Log into API Store with your account credentials.
  2. Move to Applications and click "ADD APPLICATION"
  3. Specify a name for the application, generate access token and subscribe the application to an API.

Get credentials

To retrieve API credentials:

  1. Log into API Store with your account credentials.
  2. Move to Applications / YOUR_APPLICATION_NAME and copy "Consumer key" and "Consumer secret" from "Production keys" tab.

Get access token

Get an access token either from API Store or using cURL.

To retrieve access token from API store:

  1. Log into API Store with your account credentials.
  2. Move to Applications / YOUR_APPLICATION_NAME / Production keys.
  3. Copy access token from "Access Token" input field or regenerate a new one.

To retrieve access token using cURL:

  1. Download cURL for your environment.
  2. Run the following command. For the authorization you will need a Base64 encoded string of your applications "Consumer key" and "Consumer secret" joined by a single colon ":". Replace <api_host> by the the address of the production API. You will find a valid command filled with your access token from API Store / Applications / Your Application / Production keys.
curl -k -d "grant_type=client_credentials" -H "Authorization: Basic Base64(<consumer-key>:<consumer-secret>)" https://<api_host>/token

In exchange for these credentials, Truugo authorization server returns your access token in the access_token field:

{
  "scope":"<scope>",
  "access_token":"<access_token>",
  "token_type":"Bearer",
  "expires_in":3600
}

Include this bearer token in the Authorization header with the Bearer authentication scheme in API calls to prove your identity and access protected resources.

Access tokens have a finite lifetime. The expires_in field contains the number of seconds after which the token expires. For example, an access token with an expiry value of 3600 expires in one hour from when the response was generated.

To detect when an access token expires, write code to either:

  • Keep track of the expires_in value in the token response.
  • Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.

Re-use the access token until it expires. Then, get a new token.

API requests

Log in to API store to get detailed information about each API.

See example(s) on how to send API requests.

API responses

See list of HTTP status codes returned by Truugo API.