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:

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.

Standard Flow DB Diagram

When using Connect Match

If you are using Connect Match, you should store access_tokens on a vehicle_id-basis. As Connect Match limits a user to authorizing only a single vehicle at a time, Smartcar provides a new access_token for each authorized vehicle. As you can see below, a user can grant Sky Insurance access to multiple vehicles, each with their own access_token.

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
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
async function getOdometer() {
  let access = await loadAccessFromDb();
  if (smartcar.isExpired(access.expiration)) {
    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
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
// 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);
}