Getting started with GraphQL

The GraphQL Auto API enables flexible querying of specific Auto API datapoints, allowing you to specify the data you are interested to read in a granular way. This tutorial will help you get started step by step. By following the steps you will be receiving odometer data from the car simulator.

GraphiQL Console

Introspect the Auto API schema easily with the GraphiQL console.

Introduction to GraphQL

The GraphQL data query language is a powerful way to access vehicle data from our platform. At its core, it enables you to:

  • Query datapoints you are interested in and no more.
  • Reduce the number of requests by unifying them into a single one.
  • Use a strong type system that allows you to only ask for data that is possible to return.
  • Work with clear and helpful errors for mistyped queries.
  • Use introspection - a GraphQL client can query the schema dynamically.
  • Match returning JSON easily with the query.

Endpoint URL

Note that the GraphQL URL is when working with the car emulators and for cars in production mode.

When you use the configuration snippets from the platform as shown in this tutorial, you will always be using the right URL automatically.

Auto API schema

The GraphiQL console enables discovery and inspection of the GraphQL schema.

Every query that you make in the console is validated and executed against the same schema as the production version. It's possible to query all available datapoints in the Auto API spec and static fixtures are returned.

The GraphQL schema can be inspected with any client-side library by running the query:

query {
  __schema {
    types {
      fields {

Access to vin and brand is available through a universal capability in the GraphQL schema, an can be fetched with the following:

query {
  universal {
    brand { data }
    vin { data }


GraphQL does not support fetching Firmware Version, Historical, Multi Command and Vehicle Status capabilities - support for the first 2 might be added in the future, the latter 2 are made redundant by GraphQL's granual query.

Inspection can also be done with cURL as shown here:

curl '' -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer JWT_TOKEN' \
    -d '{ "query": "query { __schema { types { name kind description fields { name } } } }" }'

Create a Cloud App

In "Develop mode" you will find your sandbox apps. In the app details page you are going to set the permissions it requires, manage devices and link virtual vehicles from your garage to test. Let's see how to create a new app.

  1. Go to the Build tab, select "Develop mode" and click the big plus (+) button, select "Fleet" or "Driver" as the type and then select "Cloud App".
  2. In the left section, select the permissions that your app needs under the "Permissions" tap.
    Note: Each permission must be manually added to each new app.
  3. You can edit your app name and image from the menu icon next to the app name.

Create a Vehicle

In the "Simulation studio" you are able to create vehicles to link with your app and to test with the simulators. Go to the simulation studio and click the big plus (+) button.

Get API Config

The first thing your app code needs to do is to provide credentials to the server. This is done through JWT and we are showing an example in this tutorial for JavaScript.

  1. Go to Develop mode, and select the app you created in the previous steps.
  2. Choose "Client certificate" in the left section and then the "GraphQL" tab.
  3. Copy the JSON snippet.
  4. Insert the snippet into into your project and assign it to a variable.

The config variable will look something like this:

  "version": "2.0",
  "type": "graph_ql_api",
  "private_key_id": "4ea88039-ad8d-4ad6-98f3-dfa732cc3df7",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgpXy8b0STpG2cZoOI\n/QBCwAglm05jynlisjzgr8tf0gihRANCAARr/0RviZRZRXs+g5lqUctZPfgLEleG\nalv0rKPlN2Z+ztHuOEdukOTFyQnOCx3R/yEwHtxckiO9hOwIzfpzHiIp\n-----END PRIVATE KEY-----",
  "app_uri": "",
  "app_id": "32CA6F235A5B9804D154EF07",
  "client_serial_number": "53C441983C0A4C8A86"

Here's an overview of the steps:

  1. Include the key-pair information in your back-end system. You can use your preferred JWT library.
  2. Create an JWT Token per example below.
  3. Use the generated JWT Token as a header in each request together with the following content type and accept headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer JWT_TOKEN

Create a JWT

The JWT should be signed using the ES256 algorithm and must contain the following claims:

verThe version of the API, taken from the version in the config
issThe application client serial number, taken from the client_serial_number in the config
audThe API URI, taken from the app_uri in the config
iatThe current datetime, formatted in the Unix timestamp format. This is used to minimize the possibilities of a replay attack, so that a JWT created in the past cannot be reused. Currently a tolerance of 30 seconds is used to account for any clock skew between our servers and the back end servers, but it can be changed, probably shortened in the future. Example value: 1502121268
jtiAn unique identifier in the UUID format of the JWT itself to ensure a JWT can be used only once.
subThe access token specific to the car, the retrieal of which is done per the next step or by the OAuth2 or Fleet Clearance flows

Send a Request

Once the simulator is open, fire away a request. For example to get the odometer of the vehicle.

If you see that the app lacks permissions, you will need to revisit step two of the "Create an App" section of this document and select the appropriate permissions for your query.

Further Reading

Check out the GraphQL Reference for all details.

curl '' -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer JWT_TOKEN' \
    -d '{ "query": "query getOdometer { diagnostics { odometer { data { value unit } } } }" }'