1. Adapt Smartcar Connect to your application architecture

Smartcar Connect is Smartcar’s OAuth 2.0 authorization flow. It is your users’ first and only touchpoint with Smartcar. After a user enters the Smartcar Connect flow and authorizes their vehicle(s), your application is able to make requests to the Smartcar API. Those requests allow your application to retrieve information and send commands to the user’s vehicle(s), such as reading the odometer and unlocking the doors.

Depending on your web or mobile application architecture, you can implement the Smartcar Connect flow in different ways.

Traditional server-side rendered application

Server-Side Rendered Application Architecture with Smartcar’s API.

  1. Your application redirects the user’s browser to Smartcar Connect. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle.
  2. The Smartcar Connect flow is now complete and the user’s browser gets redirected to a specified redirect_uri. Your application’s server, which is listening at the redirect_uri, retrieves the authorization code from query parameters in the redirect_uri.
  3. In order to exchange the authorization code for an access_token, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s client_id and client_secret.
  4. In response, Smartcar returns an access_token and a refresh_token. These should be stored in your application’s database.
  5. Using the access_token, your application can now make API requests to the user’s vehicle.

Single-page application

Single-page Application Architecture with Smartcar’s API.

  1. Using the Smartcar JavaScript SDK, your application launches Smartcar Connect in a pop-up window. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle.
  2. The user’s browser gets redirected to a special Smartcar-hosted redirect_uri. For more details on how to configure a Smartcar-hosted redirect_uri, see our API reference.
  3. Once the user has completed the Smartcar Connect flow, the onComplete callback in the JavaScript SDK is invoked with the authorization code.
  4. Your application front end sends the authorization code to its back-end service.
  5. In order to exchange the authorization code for an access_token, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s client_id and client_secret.
  6. In response, Smartcar returns an access_token and a refresh_token. These should be stored in your application’s database.
  7. Using the access_token, your application can now make API requests to the user’s vehicle.

Mobile application

Mobile Application Architecture with Smartcar’s API.

  1. Using the Smartcar iOS SDK or the Smartcar Android SDK, your application launches Smartcar Connect in a browser view. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle.
  2. The browser view gets redirected to a special custom-scheme redirect_uri. For more details on how to configure a custom-scheme redirect_uri, see our API reference.
  3. Once the user has completed the Smartcar Connect flow, the completion handler in the iOS or Android SDK is invoked with the authorization code.
  4. Your mobile application sends the authorization code to its back-end service.
  5. In order to exchange the authorization code for an access_token, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s client_id and client_secret.
  6. In response, Smartcar returns an access_token and a refresh_token. These should be stored in your application’s database.
  7. Using the access_token, your application can now make API requests to the user’s vehicle.

2. Adapt Smartcar Connect to your use case

Fit Smartcar Connect into the user journey

To increase conversions and maximize your users’ satisfaction, it is crucial to launch Smartcar Connect at the right moment in your product’s user journey.

We recommend prompting the user to connect their car through Smartcar Connect while they are onboarding their vehicle to your application for the first time.

Standard: Let the user connect one or more vehicles

In the standard Smartcar Connect flow, the user selects their car brand and logs in with the username and password of their vehicle’s connected services account. On the next screen, the user can see all vehicles associated with their account. The user can select one or multiple of these vehicles and grant your application access to them.

Standard Flow

We recommend using the standard Smartcar Connect flow whenever you don’t yet know the make or VIN of your user’s vehicle(s). If you know the make or VIN of your user’s vehicle(s), we recommend personalizing the Smartcar Connect flow in the following ways:

Optional: Skip the car brand selection screen

If you know the make of your user’s vehicle(s) prior to launching Smartcar Connect, we recommend using Brand Select. Brand Select causes the user to automatically skip the car brand selection screen. Instead, the user lands directly on their vehicle brand’s login screen. This speeds up the onboarding experience and increases conversions.

Smartcar Connect Direct

Optional: Check a vehicle’s eligibility before launching Smartcar Connect

If you know the VIN of your user’s vehicle prior to launching Smartcar Connect, we recommend using the Compatibility API. The Compatibility API lets you verify a vehicle’s eligibility before sending a user through Smartcar Connect. That way, your application will show Smartcar Connect to users with compatible vehicles only.

Note: The Compatibility API is only available for vehicles sold in the United States.

Optional: Make sure the user connects the right vehicle

If you know the VIN of your user’s vehicle prior to launching Smartcar Connect, we recommend using Single Select. Single Select causes the user to skip the car brand selection screen. It also limits them to connecting only the vehicle with that specific VIN, even if the user has registered multiple vehicles under the same connected services account. This simplifies the user experience and guarantees that the user connects the right vehicle to your application.

Smartcar Connect Match

3. Set optional and/or required permissions

When redirecting a user to Smartcar Connect, you need to include a scope parameter that indicates which permissions your application requests access to. Every vehicle endpoint has a permission name associated with it. For example, the permission name for the /fuel endpoint is read_fuel. Please see our API reference for a full list of all permission names.

Optional permissions

Not all vehicles are capable of all permissions. For example, Tesla vehicles aren’t capable of the read_fuel permission, because they don’t have fuel tanks. In order to handle this smoothly, all permissions that your application requests access to in Smartcar Connect are optional by default.

For example, let’s assume that your app requests access to the read_location and the read_fuel permissions. A user connects their Tesla vehicle through Smartcar Connect. The user is able to successfully authorize their vehicle, because both, the read_location and the read_fuel permission are optional. In the background, your application is granted permission to the read_location endpoint only, because the vehicle is incapable of the read_fuel permission.

In order to verify which permissions your application was granted access to, make a request to the /permissions endpoint:
  • 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
vehicle.permissions().then(function(response) {
  console.log(response);
});

Required permissions

If certain permissions are essential to your application’s use case, you can make them required by adding the required: prefix to each pertaining permission within the scope parameter (e.g. required:read_fuel). The user is then able to authorize a vehicle only if the vehicle is capable of all required permissions.

For example, let’s assume that you mark both read_location and read_fuel as required in the scope parameter. A user tries to connect their Tesla vehicle through Smartcar Connect. As Tesla vehicles are incapable of the read_fuel permission, the user isn’t able to successfully authorize their vehicle. Instead, Smartcar sends the vehicle_incompatible error back to your application.

  • 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
const client = new smartcar.AuthClient({
clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  redirectUri: REDIRECT_URI,
  scope: ['read_odometer', 'read_vehicle_info', 'required:read_location'],
  testMode: true,
});