​
What’s changing for my integration?

Vehicle owners will now step through two new screens within Connect to authorize access to their Tesla account. Launching and exiting the Connect flow remains unchanged.

1

Launching Connect

2

Authorize with Tesla

Currently Tesla does not check any permissions by default after a user signs in.

3

Grant Screen

Prior to launching Connect, we strongly recommend prompting your users to Select All permissions on the Tesla grant screen for the smoothest experience. Smartcar will continue to gate access to your application with our permission model on the next screen. Failure to check the the correct combination of permissions will require user action to revoke access and re-authenticate.

​
Commands

In addition to permissions from their authorization flow, Tesla now requires virtual keys for 3rd-party applications in order to issue commands for the following models:

  • All Cybertrucks, Model 3s and Ys
  • 2021+ Model S and X

Each vehicle on a Tesla account will need to have a virtual key added individually.

In order to do this, the vehicle owner needs to set up Phone as a Key prior to accepting a Third-Party Virtual Key. Failure to have these complete will result in certain requests failing e.g. lock and unlock, or charge control requests come January 2024.

​
Handling the new redirect parameter

After going through the new Connect flow, we’ll send back a URL pointing to our Third-Party Virtual Key along with the code:

Success
HTTP/1.1 302 Found
Location: https://example.com/home?
code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
&virtual_key_url=https://www.tesla.com/_ak/smartcar.com

This new param will not break existing HTTP client integrations or older SDK versions. Update to the latest version to receive the URL in the Connect onComplete for our Frontend SDKs.

handleResponse(SmartcarResponse smartcarResponse) {
    // handle code
    // retrieve virtualKeyUrl
    String virtualKeyUrl = smartcarResponse.getVirtualKeyUrl()
}

​
Adding a Virtual Key

You will need to prompt your users to open the link. Depending on your user’s device, they will need to do the following:

Adding a Virtual Key will need to be done after a user has granted Smartcar access to their Tesla account in the Connect flow.

Please see our FAQs for details on adding a virtual key for accounts with multiple vehicles and different account types.

On mobile devices, they will be redirected to the Tesla app and prompted to add a Virtual Key

Opening the link on a mobile device with the Tesla app installed

​
Virtual Keys for Smartcar Enterprise Customers

By default, Smartcar will host a Smartcar specific virtual key. This will prompt vehicle owners to approve Smartcar third party application access to their vehicle.

Smartcar’s Enterprise customers can use a virtual key specific to their branding. This allows your brand to request access to a vehicle owner’s Tesla account instead of Smartcar by default. For example, the Tesla authorization screen would read:

    Allow {{YOUR_BRAND}} access to your Tesla Account?

In addition, this will prompt vehicle owners to approve a virtual key using their brand name in the following format:

    {{YOUR_BRAND}}.app.car

When adding the virtual key via the Tesla app, a vehicle owner will see the following message:

A virtual key for "{{YOUR_BRAND}}.app.car" will be paired with your Model 3

Please reach out to your Account Manager to get the process started.

​
Updating Access with Tesla

You can use either of the following URLs to launch an Update Access flow from step 3. in the event you need to get additional Tesla permissions from the vehicle owner due to:

This flow sends a new authorization code to your callback URI in order to fetch a new access and refresh token. Use this flow if you have set up a custom branded application with its own virtual key.

    https://connect.smartcar.com/oauth/authorize?
    response_type=code
    &make=TESLA
    &update_access=true
    &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
    &scope=read_odometer control_security
    &redirect_uri=https://example.com
    &user_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
    &vehicle_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
nametyperequireddescription
response_typestringtrueThis should be set to code.
makestringtrueSpecifies the brand to update access to. Currently, the only make available for this flow is TESLA.
update_accessbooltrueSetting this to true sets the behavior of Connect to update access to the specified brand.
client_idstringtrueThe application’s unique identifier. This is available on the credentials tab of the Smartcar Dashboard.
scope[permissions]trueA space-separated list of permissions that your application is requesting access to. The valid permission names can be found in the permissions section. When reauthenticating, the user will be required to grant the corresponding OEM permissions before being able to exit the flow.
redirect_uristringtrueRequired if using the /authorize route for Smartcar to return an authorization code.
user_idstringtrueThe Smartcar user_id tied to the vehicle returned from /user
vehicle_idstringtrueThe Smartcar vehicle_id associated with the vehicle returned from /vehicles

​
Permission Mappings

These are currently the mappings of Smartcar permissions to Tesla’s. Given Tesla’s aggressive timeline we expect there may be some changes so strongly recommend prompting your users to Select All permissions in Tesla’s flow to avoid needing to update access and reauthenticate in the future.

Smartcar PermissionTesla Permission
control_chargeVehicle Charge Management
control_climateVehicle Commands
control_navigationVehicle Commands
control_pinVehicle Commands
control_securityVehicle Commands
control_trunkVehicle Commands
read_batteryVehicle Information
read_charge_recordsVehicle Charge Management
read_chargeVehicle Information
read_climateVehicle Information
read_compassVehicle Information
read_engine_oilVehicle Information
read_extended_vehicle_infoVehicle Information
read_fuelVehicle Information
read_locationVehicle Information
read_odometerVehicle Information
read_securityVehicle Information
read_speedometerVehicle Information
read_thermometerVehicle Information
read_tiresVehicle Information
read_vehicle_infoVehicle Information
read_vinVehicle Information

​
For vehicles connected via the old integration

Depending on how many Tesla accounts are associated with a vehicle, there may be changes to the user_id returned from the /user endpoint with the new access_token minted after authorizing with Tesla’s new flow.

In this example, we pass the old smartcar user_id, but you can use any identifier to indicate this is one of your existing users reauthorizing using the new flow.

Connect URL
HTTP/1.1 302 Found
Location: https://connect.smartcar.com/oauth/authorize?
    response_type=code
    &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
    &redirect_uri=https://example.com/home
    &scope=read_vehicle_info read_vin read_battery
    &flags=tesla_auth:true
    &state={old_user_id}

We’ll then send this back to you in our POST back to your redirect_uri.

Connect URL
HTTP/1.1 302 Found
Location: https://example.com/home
?code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
&virtual_key_url=https://www.tesla.com/_ak/smartcar.com
&state={old_user_id}

After fetching the initial access_token, you can fetch the user_id from /user and update your record (if applicable) in addition to saving the newly minted token pair.

If a user failed to select the corresponding Tesla permissions for the ones passed to Smartcar, you will receive a PERMISSION:NULL error when making an API request. Connect scopes this Smartcar authorization based on the intersect of your requested smartcar permissions with the ones selected by the user on Tesla’s side.

Was this page helpful?

What's New?FAQs