Overview of the RTA API

The RTA API is the gateway to data and intelligence in RTA Fleet Management software. You can use the RTA API to build apps for your organization and consumers that interact with the data in RTA Fleet Management software. With the RTA API, you can connect to a wealth of resources, relationships, and intelligence, all through a single endpoint: https://api.rtafleet.com.

Get access tokens to call the RTA API

To call the RTA API, your app must acquire an access token from Auth0, RTA's cloud identity service. The access token contains information (or claims) about your app and the permissions it has for the resources and APIs available through the RTA API. To get an access token, your app must be able to authenticate with Auth0 and be authorized by either a user or an administrator for access to the the RTA API resources it needs.

This topic provides an overview of access tokens, OAuth and how your app can get access tokens.

What is an access token and how do I use it?

Access tokens issued by OAuth are base 64 encoded JSON Web Tokens (JWT). They contain information (claims) that the RTA APIs use to validate the caller and to ensure that the caller has the proper permissions to perform the operation they're requesting. When calling the RTA API, you can treat access tokens as opaque. You should always transmit access tokens over a secure channel, such as transport layer security (HTTPS).

Here's an example of an RTA access token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik9UWTVNVUk1TXpKQk9EWkdSVUU0TXpReVFURTVNRU0zTWpKQ05ESXlOa06T0VVek9URXdOdyJ9.eyJodHRwczovL2FwaS5ydGFmbGVldC5jb20vYXBwX21ldGFkYXRhIjp7InRlbmFudElkIjoiUlRBMDEyNjciLCJpZCI6Ikx1VUxUYU9CcTJhcjJzRlBiaHJMRmVROElQcklVNFoyIiwiaXNNYWNoaW5lMk1hY2hpbmUiOnRydWUsImRlc2t0b3BVc2VybmFtZSI6InN5c3RlbSJ9LCJpc3MiOiJodHRwczovL2Rldi1ydGEuYXV0aDAuY29tLyIsInN1YiI6Ix1VUxUYU9CcTJhcjJzRlBiaHJMRmVROElQcklVNFoyQGNsaWVudHMiLCJhdWQiOiJodHRwczovL3N0Zy5hcGkucnRhaGl2ZS5jb20iLCJpYXQiOjE1NDQ3MTUwNDYsImV4cCI6MTU0NzMwNzA0NiwiYXpwIjoiTHVVTFRhT0JxMmFyMnNGUGJockxGZVE4SVBySVU0WjIiLCJzY29wZSI6InBhcnRzOnZpZXciLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.izNktviwQnmj4yl5mrXLvmdRNyRfJste6fryhmtmEtNacY3ehgEilrrjfpBAgqAhqV8efuB9nkO2x27Bn-P76RHaFYUd5bWHveNCcwRkyLrj51C9_EENpzsjhh1_PU1cDaG15Ruil0LunM_4zSJ_4XIaipHwdDtBx5LatSLqcf5yy2YsKD9pKDfSmIxkYkpiJz_xyUKFW96H45n2cXlgGFoz 2j8skLZITVKQwFp1yJ_CfxmlTkJZ9ZQIQpWUd2PVtzCVCNDq26FJbnJjKX45UhwSw3wb5v-S5sRkDzQl4WYDbRfAf3bCmPmpFrSstp2uvw3_CMvirENT2NE0KPIuGQ

HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLC ... CMvirENT2NE0KPIuGQ
Host: api.rtafleet.com
POST /graphql HTTP/1.1
{ "query": "{ getMe { id } }"}

To call the RTA API, you attach the access token as a Bearer token to the Authorization header in an HTTP request. For example, here's a call that returns the profile information of the signed-in user (the access token has been truncated for readability)

What are the RTA API permissions?

The RTA API exposes a rich set of granular permissions over the resources it controls. These permissions are expressed as strings and grant apps access to the RTA API resources like vehicles, parts, work orders, purchase orders, etc. For example:

vehicles:view allows an app to read the vehicles in the RTA system.
parts:update allows an app to update part details.

There are two types of permissions:

Delegated permissions are used by apps that run with a user present. The user's privileges are delegated to the app which makes calls on behalf of the user to the RTA API. Many of these permissions can be consented to by a user, but others require administrator consent.
Application permissions are used by apps that run without a user. These often grant an app broad privileges within an organization and always require the consent of an administrator.

For a complete list of the RTA API permissions, as well as the differences between delegated and application permissions, see the Permissions reference.

Where does my app get an access token?

Your app gets access tokens from Auth0, RTA's cloud identity service. To get an access token, your app exchanges HTTP requests and responses with Auth0 using industry-standard protocols defined in the OAuth 2.0 specification. These protocols describe the Auth0 endpoints and exchanges with them -- or authentication flows -- that your app uses to securely authenticate with Auth0 and get access tokens.

On a very simple level, to get an access token, your app exchanges HTTP requests with the following endpoints:

The /authorize endpoint, where your app can send a user to authenticate with Auth0 and consent to the permissions your app needs. The /token endpoint where your app can get an access token once user consent has been granted. (Note: These definitions are not rigid. Depending on the protocol your app uses, it may get access tokens directly from the /authorize endpoint or it may authenticate directly with the /token endpoint.)

Here's an example of one set of the /authorize and /token endpoints exposed by Auth0:

https://rtafleet.auth0.com/authorize
https://rtafleet.auth0.com/token

Register your app with the RTA API

Your app must be registered with RTA. Registering your app establishes a unique application ID and other values that your app uses to authenticate with Auth0 and get tokens. You register your app by creating an API Key on the RTA Web App. More info can also be found here Depending on the type of app you are developing, you will need to copy one or more properties during registration to use when you configure authentication and authorization for your app.

Get access without a user

Some apps call the RTA API with their own identity and not on behalf of a user. In many cases, these are background services or daemons that run on a server without the presence of a signed-in user. An example of such an app might be a data extraction service that wakes up and runs overnight. In some cases, apps that have a signed-in user present may also need to call the RTA API under their own identity. For example, an app may need to use functionality that requires more elevated privileges in an organization than those carried by the signed-in user.

Apps that call the RTA API with their own identity use the OAuth 2.0 client credentials grant flow to get access tokens from Auth0. In this topic, we will walk through the basic steps to configure a service and use the OAuth client credentials grant flow to get an access token.

Authentication and authorization steps

The basic steps required to configure a service and get a token from the Azure AD v2.0 endpoint that your service can use to call the RTA API under its own identity are:

Register your app.
Configure permissions for the RTA API on your app.
Get an access token.
Use the access token to call the RTA API.

Get an access token

In the OAuth 2.0 client credentials grant flow, you use the Application ID and Application Secret values that you saved when you registered your app to request an access token directly from the Azure AD v2.0 /token endpoint.

Get access token

POST /oauth/token HTTP/1.1
Host: rtafleet.auth0.com
Content-Type: application/json
cache-control: no-cache
{
  "audience": "https://api.rtahive.com",
  "grant_type": "client_credentials",
  "client_id": "LuULTaO2sFPbhrLFe...PrIU4Z2",
  "client_secret": "jsAt0vbpF3...Gqu-LYMOq0y7tYOrFyKABDovFMuZMMCfgIB"
}

You send a POST request to the /token endpoint to acquire an access token.

audience: Must be https://api.rtahive.com
client_id: The Application ID that the RTA Support team assigned when you registered your app.
client_secret: The Application Secret that was generated for your app by the support team.
grant_type: Must be client_credentials

A successful response looks like this:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik9UWTVNVUk1TXpKQk9EWkdSVUU...",
  "scope": "parts:view",
  "expires_in": 2592000,
  "token_type": "Bearer"
}

A successful response contains the following:

access_token: The requested access token. Your app can use this token in calls to the RTA API.
scope: This value contains all the application permissions you have configured for your app.
token_type: Indicates the token type value. The only type that Azure AD supports is bearer.
expires_in: How long the access token is valid (in seconds).

Supported app scenarios and resources

Apps that call the RTA API under their own identity fall into one of two categories:

Background services (daemons) that run on a server without a signed-in user.
Apps that have a signed-in user but also call the RTA API with their own identity; for example, to use functionality that requires more elevated privileges than those of the user.
Apps that call the RTA API with their own identity use the OAuth 2.0 client credentials grant to authenticate with Azure AD and get a token.

Permissions

Permissions in RTA are enforced based on Application identity accessing the API. A list of applications can be found in the RTA Web App when editing an API Key here

Code Samples

Code samples that demonstrate using the RTA API are available in the RTA Developer Samples GitHub repository.

Use the RTA API Version 2

There are 2 versions of the RTA API. The first version is what a majority of these docs pertain to, our graphql api.

Our version 2 api docs can be found here

Authentication is handled the same as the version 1 api, though a token CAN be generated through the version 2 api via the following endpoint: getApiToken

Use the RTA API Version 1

The RTA API is a GraphQL web API that enables you to access RTA API service resources. After you register your app and get authentication tokens for a user or service, you can make requests to the RTA API.

https://api.rtafleet.com/graphql

Request body format

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

The components of a request include:

HTTP method - For RTA API, this will always be POST
Content type: application/json
Body: JSON-encoded body of the following form:

After you make a request, a response is returned that includes:

Response data format

{
  "data": { ... },
  "errors": [ ... ]
}

Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
data - The data that you requested or the result of the operation. The response message can be empty for some operations. If your request returns a lot of data, you need to page through it. For details, see Paging.
errors - Any errors that occur will be included.

A query might result in some data and some errors, and those should be returned in a JSON object of the form:

If there were no errors returned, the "errors" field should not be present on the response.

Sample request and response to retrieve user profile and permissions

Request

query fetchMe {
  getMe {
    id
    status{
      code
      state
    }
    permissions {
      tenantId
      facilityId
      permission
    }
    tenants {
      id
      name
      roles {
        id
      }
    }
  }
}

Response

{
  "data": {
    "getMe": {
      "id": "LuULTaOBq2ar2rLFeQ8IPrIU4Z2",
      "status": null,
      "permissions": [],
      "tenants": [
        {
          "id": "RTA99999",
          "name": "RTA Sample Customer",
          "roles": []
        }
      ]
    }
  }
}

Exploring the GraphQL Schema

Visit https://graphqlbin.com.
Select URL ENDPOINT and enter the Endpoint url for the RTA API: https://api.rtafleet.com/graphql.

Exploring the Docs

On the right side of GraphQL Playground, you will find a tab called DOCS which you an use to explore the queries and mutations available in the RTA API.

Examples

Example 1: Querying basic tenant information

Request

{
  getTenant(input: { id: "RTACAN01" }) {
    id
    name
    entitlements
  }
}

This sample demonstrates how to retrieve basic tenant information. Notice how GraphQL allows the developer to specify the exact data required in the response.

Response

{
  "data": {
    "getTenant": {
      "id": "RTACAN01",
      "name": "RTA Canary 01",
      "entitlements": null
    }
  }
}

Errors

{
  "data": { ... },
  "errors": [ ... ]
}

The RTA API returns error information as part of the response. A query might result in some data and some errors, and those should be returned in a JSON object of the form shown at the right.

Sample invalid request

query {
  getParts(input: {tenantId: "INVALID_ID", facilityId: "200"}) {
    parts {
      id
      partNumber
    }
  }
}

If there were no errors returned, the "errors" field will not be present on the response.

Field	Description
`message`	The error message.
`extensions`	Additional information about the error.
`exception`	Exception/Error details.
`requiredPermission`	The permission required to execute the requested operation.

Sample error response

{
  "data": null,
  "errors": [
    {
      "message": "Missing required \"parts:view\" permission.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "getParts"
      ],
      "extensions": {
        "code": "API.MISSING_PERMISSION_PARTS_VIEW",
        "exception": {
          "code": "API.MISSING_PERMISSION_PARTS_VIEW",
          "type": "MISSING_REQUIRED_PERMISSION",
          "description": "Missing required \"parts:view\" permission.",
          "tokens": {
            "requiredPermission": "parts:view"
          },
          "ctx": {
            "awsRequestId": "a1772866-ffbe-11e8-bd7e-b91d02e81301",
            "correlationId": "a15b14c4-ffbe-11e8-bc70-19caf995b12d",
            "info": {
              "getPartsGraphql": "2018-12-14T16:38:05+00:00",
              "fetchPartsApi": "2018-12-14T16:38:05+00:00"
            }
          }
        }
      }
    }
  ]
}

Paging

Paging of records is handled as part of the request to any of the plural methods in the RTA API using the queryOptions.pagination element in the GraphQL query.

When a response is returned, a set of meta data is supplied which provides additional pagination information indicating the current page, totalPages, totalRecords, current offset and current limit

Terms

Term	Meaning
`offset`	The number of records to skip. This is a zero-based number meaning that the first record is represented by the number 0; the tenth record by the number 9.
`limit`	The maximum number of records to return in the query.
`page`	The current page number.
`totalPages`	The total number of pages given the current `limit`.
`totalRecords`	The total number of records available.

Paged result request

query {
  getParts(input: {
      tenantId: "RTA99999",
      facilityId: "200",
      queryOptions: {
          pagination: {
              offset: 0,
              limit: 50
              }
        }
    }) {
    parts {
      id
      partNumber
      description
      meanCost
      sellingPrice
    }
    meta {
      page
      totalPages
      totalRecords
      offset
      limit
      sort {
        sortBy
        sortOrder
      }
      searchMeta {
        id
        relevancy
      }
    }
  }
}

Response, results truncated for brevity

{
  "data": {
    "getParts": {
      "parts": [
        {
          "id": "00096F4A5EB1A82C67F6BD8DFE9744BB",
          "partNumber": "10W30",
          "description": "10W30 Motor Oil",
          "meanCost": 2.43,
          "sellingPrice": 3.43
        },
        {
          "id": "000A87043FAC8438CDF312974E95CCB2",
          "partNumber": "D1770",
          "description": "Brake Pads - Front",
          "meanCost": 21.5,
          "sellingPrice": 37.99
        }
        ...
      ],
      "meta": {
        "page": 1,
        "totalPages": 74,
        "totalRecords": 3698,
        "offset": 0,
        "limit": 50,
        "sort": {
          "sortBy": "id",
          "sortOrder": "asc"
        },
        "searchMeta": null
      }
    }
  }
}

Extracting data from RTA

RTA has built a simple REST API for extracting useful data directly from the RTA database. This is useful for customers who need direct access to the raw, unformatted data for use in data warehousing and other utility projects.

The data returned represents the actual physical column names in the database.

The data extract API can be used by first obtaining an access token as descrbed in this documentation. The access token is then used as a bearer token in the authorization header.

Required Permission

A special API permission has been created to allow use of the data extract API. We recommend tighly controlling and securing the client id and client secret when granted this permission because anyone with these credentials will have full read access to all of the data in your database.

Permission Name	Description
api:extractTable	gives full read access to all tables in the customer database

URL format of the extract API

Use the following URL to access the data extract API.

URL: https://api.rtafleet.com/v0/extract/<tablename>?etag=<etag>&limit=<limit>

Field	Description
`tablename`	The name of the actual table in the RTA database. To obtain the table names you may request the data dictionary by contacting support@rtafleet.com
`etag`	The first etag value to return
`limit`	limit is not required, has a max of 1000 and defaults to 1000. If you choose to get your data in increments of 100, you could set limit=100.

Examples calling the API

See the example at the right for the format of the data returned from the API.

The resulting object is:

{
    "count": 1000,
    "value" : [the rows from the table sorted by etag],
     "nextEtag" : "12344"
}

where nextEtag would be the very next etag value to use. nextEtag is not returned if you have received all the rows in the table.

Retreive the first 1000 records

Example retrieving records from vehfile

curl --request GET \
  --url "https://api.rtafleet.com/v0/extract/vehfile?etag=0&limit=1000" \
  --header "authorization: Bearer $AUTH_TOKEN"

Sample reponse from vehfile

{
    "count":"1000",
    "value":[
        {FIRST RECORD IN TABLE},
        ...,
        {1000th RECORD IN TABLE}
    ],
    "nextEtag":"12345"
}

See the example CURL request at the right to retrieve the first 1000 records from the vehilces table vehfile.

Retrieve any rows modified since the etag 12345

Sample request with etag

curl --request GET \
  --url "https://api.rtafleet.com/v0/extract/vehfile?etag=12345&limit=1000" \
  --header "authorization: Bearer $AUTH_TOKEN"

Sample response without nextEtag

{
    "count":"50",
    "value":[
        {1001th RECORD IN TABLE},
        ...,
        {1051th RECORD IN TABLE}
    ]
}

See the example CURL request at the right to retrieve anything that has been created or modified since the etag of 12345 has been retrieved.

Because nextEtag was not returned, there are no more rows to retrieve.

Errors in the data extract API

If you supply an invalid tablename, you will receive a 404 error.