Upgraded Tesla API Integration
This page has information regarding Smartcar’s upgraded Tesla integration and what this means for developers. For an overview of the changes see this page.
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.
Launching Connect
Authorize with Tesla
Currently Tesla does not check any permissions by default after a user signs in.
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
:
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:
- A PERMISSION error from API
- A CONNECTED_SERVICES_ACCOUNT:PERMISSION error from API
- Needing access to an endpoint out of scope for your existing permissions
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
name | type | required | description |
---|---|---|---|
response_type | string | true | This should be set to code . |
make | string | true | Specifies the brand to update access to. Currently, the only make available for this flow is TESLA . |
update_access | bool | true | Setting this to true sets the behavior of Connect to update access to the specified brand. |
client_id | string | true | The application’s unique identifier. This is available on the credentials tab of the Smartcar Dashboard. |
scope | [permissions] | true | A 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_uri | string | true | Required if using the /authorize route for Smartcar to return an authorization code. |
user_id | string | true | The Smartcar user_id tied to the vehicle returned from /user |
vehicle_id | string | true | The 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 Permission | Tesla Permission |
---|---|
control_charge | Vehicle Charge Management |
control_climate | Vehicle Commands |
control_navigation | Vehicle Commands |
control_pin | Vehicle Commands |
control_security | Vehicle Commands |
control_trunk | Vehicle Commands |
read_battery | Vehicle Information |
read_charge_records | Vehicle Charge Management |
read_charge | Vehicle Information |
read_climate | Vehicle Information |
read_compass | Vehicle Information |
read_engine_oil | Vehicle Information |
read_extended_vehicle_info | Vehicle Information |
read_fuel | Vehicle Information |
read_location | Vehicle Information |
read_odometer | Vehicle Information |
read_security | Vehicle Information |
read_speedometer | Vehicle Information |
read_thermometer | Vehicle Information |
read_tires | Vehicle Information |
read_vehicle_info | Vehicle Information |
read_vin | Vehicle 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.
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
.
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?