Pricing

Docs

Getting started

Authorization

To make requests to a vehicle from a web or mobile application, your end user must connect their vehicle using Smartcar Connect. 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. Redirect to Connect - Your application redirects the user to Connect.
  2. Connect prompts for consent - Connect prompts the user to log in with their connected car account. Once logged in, the user will be asked to grant your application access to a specific scope of permissions.
  3. Handle response - If the user successfully accepts the permissions, Connect will respond with an authorization code and will redirect the user back to your application using the redirect_uri. If an error occurs, Connect will respond with an error message.

1. Redirect to Connect

A user has to grant your application access to their vehicles, therefore your application has to redirect them to Connect.

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: ['required: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 attributes, we are requesting for the read_vehicle_info permission. Refer to our API reference for the list of available permissions.

In this step, Connect displays a consent window that prompts the vehicle owner to log in with the username and password for their vehicle's connected services account. The owner will then decide whether they wish to grant your application access to their vehicle.

3. Handle response

If the user grants your application access to the set of permissions, Connect 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 username or password is valid for each brand.

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

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

Notice once you log in, Connect 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!