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 Telsa 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.

For existing vehicles

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.

This method uses the state parameter of the Connect URL to check if an older Smartcar user_id has changed.

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.

Testing the new Connect flow

You can pass ?flags=tesla_auth:true as a feature flag in your Connect URL. This will allow you to test out or send a subset of your traffic through the new flow until Dec 18, 2023.

Connect URL with the feature flag
HTTP/1.1 302 Found
Location: https://connect.smartcar.com/oauth/reauthenticate?
response_type=vehicle_id
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&vehicle_id=sc4a1b01e5-0497-417c-a30e-6df6ba33ba46
&redirect_uri=https://example.com/home
&flags=tesla_auth:true
&state=0facda3319

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 Model 3 and Y
  • 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 acounts with multiple vehicles and differnt 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 as a third party. Smartcar’s Enterprise customers can use a virtual key specific to their branding. This will prompt vehicle owners to approve the key using their brand name.

You’ll need to serve a public key provided by your Account Manager at https://$DOMAIN/.well-known/appspecific/com.tesla.3p.public-key.pem where $DOMAIN is the domain where you would like to serve the virtual key file from.

This domain path must return a 200 response code with the file, a 3xx will not work.

This domain will appear when your users add your virutal key. For example, serving the file at:

https://some.domain.com/.well-known/appspecific/com.tesla.3p.public-key.pem

will display:

A virtual key for "some.domain.com" will be paired with your Model 3

in the Tesla app.

Revoking Access with Tesla

Within Connect

When using the required: prefix for Smartcar permissions, or in cases where the user doesn’t check the Vehicle Information permission in Tesla’s auth flow, Smartcar will send the user through a Revoke Access flow in order to get the necessary permissions you need instead of allowing a connection to go through.

1

Launching Connect

2

Authorize with Tesla

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

3

Missing Permissions

4

Revoke Access with Tesla

Stand-alone Flow

You can use the following URL to launch a Revoke Access flow from step 3. in the event you need to get additional Tesla permissions from the vehicle owner due to:

    https://connect.smartcar.com/oauth/reauthenticate?
    response_type=none
    &make=TESLA
    &revoke_access=true
    &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
    &scope=read_odometer control_security
nametyperequireddescription
response_typestringtrueThis value must be set to none.
makestringtrueSpecifies the brand to revoke access to. Currently, the only make available for this flow is TESLA.
revoke_accessbooltrueSets the behavior of the reauthenticate flow to revoke 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.

After revoking access, the user will be taken through Connect again:

  • If they select the relevant permissions on Tesla’s side, they will be met with a success message and can exit the flow. Your existing Smartcar token pair will still be valid and can be refreshed as usual.
  • If they do not select the relevant permissions they will be sent back through the Revoke Access flow, and prompted to reconnect again.

Permission Mappings

These are currently the mappings of Smartcar permissions to Tesla’s. Given Tesla’s aggresive 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 revoke access and reauthenticate in the future.

Smartcar PermissionTesla Permission
control_chargeVehicle Charge Management
control_climateVehicle Commands
control_navigationVehicle 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