Skip to main content

Smartcar

In order to register a vehicle through Smartcar, you need to:

  1. Retrieve authorization URL.
  2. Redirect user to the retrieved authorization URL and let user provide credentials.
  3. Register listener on a callback URL to receive authorization code.
  4. Send authorization code to Hiven.

Prerequisites​

Before starting registering vehicle, you need to send Hiven the redirectUri (URL you want Smartcar to redirect back after successful authentication) to be added to the whitelist.

Step 1: Retrieve Authorization URL​

GET /v1/hiven/devices/smartcar/authorization-url
X-Api-Key: <apiKey>
X-User-Id: <userId>

Query parameters

{
  "manufacturer": "<string>",
  "redirectUri": "<string>",
  "countryCode": "<string>",
  "mode": "<string>"
}
  • manufacturer - vehicle manufacturer

The list of all supported vehicle manufacturers:

enum VehicleManufacturer {
  BMW = 'BMW',
  CITROEN = 'CITROEN',
  CUPRA = 'CUPRA',
  DACIA = 'DACIA',
  DS = 'DS',
  FORD = 'FORD',
  HYUNDAI = 'HYUNDAI',
  JAGUAR = 'JAGUAR',
  JEEP = 'JEEP',
  KIA = 'KIA',
  LAND_ROVER = 'LANDROVER',
  MG = 'MG',
  MINI = 'MINI',
  OPEL = 'OPEL',
  PEUGEOT = 'PEUGEOT',
  SKODA = 'SKODA',
  TESLA = 'TESLA',
  TOYOTA = 'TOYOTA',
  VAUXHALL = 'VAUXHALL',
  VOLKSWAGEN = 'VOLKSWAGEN',
  VOLVO = 'VOLVO',
}
  • redirectUri - URL you want Smartcar to redirect back after successful authentication. Once redirected, there will be a code property in query parameters which will be needed for the next step
  • countryCode - country code of the user (In ISO 3166-1 alpha-2 format, default value: FI)
  • mode - Smartcar mode (default value: live)

The list of supported Smartcar modes:

type SmartcarVehicleAuthorizationMode = 'live' | 'test' | 'simulated';
  • live - production mode, requires users to use production credentials to add real vehicle
  • test - test mode, allows users to provide dummy credentials to add a test vehicle
  • simulated - simulated mode, requires users to use simulated credentials to add simulated vehicle

Response

{
  "authorizationUrl": "<string>"
}

Step 2: Redirect User to Authorization URL​

Example authorization URL:

https://connect.smartcar.com/oauth/authorize
      ?make=<make>&redirect_uri=<redirectUri>&response_type=code
      &flags=country:<countryCode>&mode=<mode>
      &scope=required:read_battery+required:read_charge+required:control_charge+required:read_vehicle_info+required:read_vin+read_location
      &single_select=true&client_id=<clientId>
  • make - vehicle manufacturer (providing this argument allows users to bypass the "Brand Selector" screen and lets the Smartcar know that we're targeting specific brand)
  • redirect_uri - redirect URI that will receive authorization code
  • response_type - defaults to: code to support "Authorization Code Flow"
  • flags - defaults to: country:<countryCode> to indicate that the vehicle belongs to specific country

If no flag is passed or set as default on Dashboard, Smartcar will use the devices IP to set an appropriate country. This flag determines what brands are listed on the "Brand Selector" screen.

  • mode - Smartcar mode, defaults to: live to indicate that the application is being used in production mode
  • scope - a space-separated list of permissions that Hiven is requesting access to

Permissions are optional by default (like: read_location), however it is possible to make them required by adding required:<permission> prefix (like: required:read_battery).

  • single_select - when true, prevents users from selecting multiple vehicles at the same time
  • client_id - application's unique identifier managed by Hiven

Redirect user to it and let the user provide credentials.

Step 3: Receive Authorization Code​

In the first step, you provided redirectUri parameter Smartcar should redirect to with the authorization code.

Make sure you have this route defined in your system, so as soon as it's hit, you can trigger the call to send authorization code to Hiven.

An additional query parameters will be attached to the defined redirectUri:

  • code - authorization code that should be exchanged to access token
  • virtual_key_url - optional parameter that is present only for Tesla due to its specific API (default value: https://www.tesla.com/_ak/smartcar.com)

Step 3.1: Tesla-Specific Virtual Keys​

Tesla requires Virtual Keys for 3rd-party applications in order to issue commands for the following models:

  • Model 3
  • Model Y
  • Model S (2021+)
  • Model X (2021+)

If you receive virtual_key_url in query parameters, you have to redirect users to its value, which will open Tesla mobile application on mobile or Tesla webpage on desktop.

Users would have to follow provided instructions.

Mobile:

  • Tesla application opens automatically and prompts users to add a Virtual Key

If Tesla app is not installed, user will be requested to install it first.

Desktop:

  • Tesla webpage opens automatically and users have to scan QR code which opens up Tesla application, which prompts users to add a Virtual Key

Step 4: Send Authorization Code To Hiven​

Read authorization code (code) from query parameters and send it to Hiven.

Hiven will take care of exchanging code to tokens and keeping the tokens up to date.

POST /v1/hiven/devices/smartcar/connect
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "authCode": "<authCode>",
  "redirectUri": "<redirectUri>"
}
  • authCode - authorization code that should be exchanged to access token
  • redirectUri - redirect url (should match the one passed to retrieve authorization URL)

Response

{
  "deviceId": "<string>",
  "message": "<string>"
}
  • deviceId - id of the newly added vehicle
  • message - information about registration state of the vehicle - whether it was already added to the system or not

Response Status Code

  • 200 - vehicle is already added to your account
  • 201 - vehicle has been successfully added
  • 409 - vehicle is already added to another user's account
  • 500 - internal server error

Step 5: Validate Start/Stop Capability (Optional)​

Validation is useful to verify if vehicle is smart-charge capable without pairing a charger or if Tesla Virtual Key for 3rd-party was not granted.

Read more