Choose a back-end SDK

Our API SDKs simplify the process of integrating Smartcar into your application and making API requests. Select your application’s back-end language to install an API SDK:

Alternatively, choose another back-end framework

If you choose not to use one of our SDKs, you may be able to utilize the following additional frameworks:

To utilize an alternative SDK, follow the setup guidelines through their official documentation, and follow the steps in the next section.

Store and refresh tokens

1. Store access tokens

You need an access_token in order to make requests to the Smartcar API. For your application’s security, your front end should never have access to the access_token. Please store all access_tokens in a persistent store in your back end (e.g. SQL DB or session store). To learn more about access_tokens, please refer to the OAuth2 protocol.

When using the standard Smartcar Connect flow

If your application uses the standard Smartcar Connect flow, you should store access_tokens on a smartcar_user-basis. A smartcar_user identifies a single connected services account (e.g. user@example.com’s Volkswagen Car-Net account). A single connected services account may contain multiple vehicles (e.g. a 2016 e-Golf and a 2018 Passat). You can retrieve the Smartcar user_id using the /user endpoint.

Below you can see an example database schema for an application called “Sky Insurance.” By successfully completing the Smartcar Connect flow, a user can grant Sky Insurance access to multiple vehicles under a single smartcar_user. In order to allow multiple Sky Insurance customers to connect vehicles that share the same connected services account, we recommend creating a composite primary key on (user_id, sky_insurance_customer_id) in the smartcar_user table.

Standard Flow DB Diagram

When using Single Select

If you are using Single Select, you should store access_tokens on a vehicle_id-basis. As Single Select limits a user to authorizing only a single vehicle at a time, Smartcar provides a new access_token for each authorized vehicle. In order to allow multiple Sky Insurance customers to connect to the same vehicle, we recommend creating a composite primary key on (vehicle_id, sky_insurance_customer_id) in the smartcar_vehicle table.

Connect Match DB Diagram

2. Refresh access tokens

Your access_token expires every two hours. Prior to making an API request, check if your access_token has expired. If necessary, refresh the access_token before making the request, and update your persistent storage.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
async function getOdometer() {
  let access = await loadAccessFromDb();
  if (access.expiration < Date.now()) {
    access = await client.exchangeRefreshToken(access.refreshToken);
    saveAccessIntoDb(access);
  }
  const vehicle = new smartcar.Vehicle(vehicleId, access.accessToken);
  const response = await vehicle.odometer();
  return response.distance;
}

3. Refresh refresh tokens

Your refresh_token expires every 60 days. If you refresh access_tokens only prior to making a request to Smartcar, and if you don’t make any requests for 60 days, the refresh_token will expire and the user’s vehicle will become inaccessible. In that case, the only way to regain access to the vehicle is to send the user through Smartcar Connect once again.

In order to avoid this situation, run a daily scheduled job that checks which refresh_tokens are close to expiration and that refreshes them if necessary.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
// SELECT refresh_token, refresh_expiration
// FROM smartcar_tokens
// WHERE refresh_expiration < NOW() - INTERVAL '5 days';

for (let row of rows) {
  const access = await client.exchangeRefreshToken(row['refresh_token']);
  await saveAccessIntoDb(access);
}