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 Telsa 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.
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.
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.
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.
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:
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 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.
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.
Launching Connect
Authorize with Tesla
Currently Telsa does not check any permissions by default after a user signs in.
Missing Permissions
Revoke Access with Tesla
Stand-alone Flow
You can use either of the following URLs 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:
- 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
https://connect.smartcar.com/oauth/authorize?
response_type=code
&make=TESLA
&revoke_access=true
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&scope=read_odometer control_security
&redirect_uri=https://example.com
| name | type | required | description |
|---|---|---|---|
response_type | string | true | This should be set to none for /reauthenticate or code for /authorize. Setting this value to code will issue a new authorization code to exchange for a new access and refresh token pair after a vehicle owner grants your application access. |
make | string | true | Specifies the brand to revoke access to. Currently, the only make available for this flow is TESLA. |
revoke_access | bool | true | Sets the behavior of the reauthenticate flow to revoke 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 and authorization code. |
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 Permission | Tesla Permission |
|---|---|
control_charge | Vehicle Charge Management |
control_climate | Vehicle Commands |
control_navigation | 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 |
Was this page helpful?