Getting Started

Authorization

To make requests to a vehicle from a web or mobile application, your end user must connect their vehicle using Smartcar's authorization flow. This flow follows the OAuth2 authorization code grant to gain access to resources on Smartcar.

To obtain the authorization code, there are three steps -

  1. Launch the Smartcar Authorization Dialog - Your application redirects a vehicle owner to the Smartcar authorization dialog
  2. Smartcar Prompts for Consent - Smartcar prompts the vehicle owner to log in and approve the requested permissions
  3. Handle Smartcar's Response - Handle the authorization code returned by Smartcar

Step 1: Launch Smartcar Authorization Dialog

A user has to grant your application access to their vehicles, therefore your application has to redirect them to Smartcar's authentication dialog.

To do this, you will first need to set up your Smartcar auth client and retrieve the url to redirect your user to. Open up your favorite text editor and edit the stubbed file.

  • 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
// ./index.js

// TODO: Authorization Step 1a: Launch Smartcar authentication dialog
const client = new smartcar.AuthClient({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.REDIRECT_URI,
  scope: ['read_vehicle_info'],
  testMode: true,
});

app.get('/login', function(req, res) {
  // TODO: Authorization Step 1b: Launch Smartcar authentication dialog
  const link = client.getAuthUrl();
  res.redirect(link);
});

The testMode parameter is set to true to allow you to send a request to simulated accounts and vehicles on the Smartcar platform.

The scope parameter takes in the list of permissions an application wants access to. For example, since our application wants to display vehicle information, we are requesting for the read_vehicle_info permission. Refer to our API Reference for the list of available permissions.

In this step, Smartcar displays a consent window that prompts the vehicle owner to log in with their connected car credentials. The owner will then decide if they wish to grant your application access to their vehicle.

Step 3: Handle Smartcar's Response

If the user grants your application access to the set of permissions, Smartcar will return an authorization code to your redirect_uri as a query parameter.

The authorization code represents a user consenting your application access to their vehicle. It does not grant access to the vehicle itself.

In the previous section, we had set our redirect_uri as http://localhost:8000/exchange. Now, our server can be set up as follows to receive the authorization code.

  • 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
// ./index.js

app.get('/exchange', function(req, res) {
  // TODO: Authorization Step 3: Handle Smartcar response
  const code = req.query.code;

  console.log(code);

  res.sendStatus(200);
});

Try It Out

Let's try authenticating a vehicle in test mode.

In test mode, any login credentials for all brands are valid!

Start your server, open up your browser and go to http://localhost:8000/login.

  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
  • $
node index.js

Notice once you log in, Smartcar showcases all the permissions your application is asking for, in this case, read_vehicle_info. A user has to consent to all the permissions.

Once you have logged in and accepted the permissions, you should see an authorization code printed to your console.


In the next section, we will cover how to exchange the authorization code for an access_token and make your first request to Smartcar API with it!