tesla_api 3.0.3 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36800b87fde594b317de4423717ddddde20b02a89a29dcc3030da421c857961d
-  data.tar.gz: a7578ddecc3e79faaf4b91eec431196fdd42cc6b2697d8a47c115a9839beb13d
+  metadata.gz: 5b774bab2f43b76262fa9c4ab04ae250f9f325955f028d3c8bd44416f5a015f5
+  data.tar.gz: 157c7c913712cd7bc3e7412aead4225c5502b26399f7dcf2243a3f522c72cec9
 SHA512:
-  metadata.gz: 4cefac51f88134ddb5cf93567046c63249c48aac76c19ea95006f7a8f98e97ad2258c1d4969be3cedc3dd8e3ec8ad21513cc1b29913982f11b2263ca44e2bc2e
-  data.tar.gz: 3724b8215a83bd514ab27ddc02165793052f54dfb1bfc45cfe3f90c18fd50395dcedadd4e7070c3469d2f5557fb3354c02e97a3850e33c2d1ed8c397b4e8cef9
+  metadata.gz: 1354ad7bf60037cf9e09541d7122aed4448946262177e0c6a535f303fde5e5a479f15b2bda193102e305ec2f0743e9d4499aff27cbc2a452add543d64ee1157c
+  data.tar.gz: 980f1b1d752b674ab29ab82982c4ff687f3f22b62dc0c1d5aa138ef5fdd458393a7cea7177f67ae15ae64635154cd45eb7b70cf1bab12affa2c33ad9e622b32e

data/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+
+    env:
+      TESLA_EMAIL: elon.musk@teslamotors.com
+      TESLA_PASS: oilLOL
+      TESLA_CLIENT_ID: 1
+      TESLA_CLIENT_SECRET: 2
+      TESLA_ACCESS_TOKEN: 3
+      TESLA_REFRESH_TOKEN: 4
+
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0']
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run test suite
+        run: bundle exec rake

data/.tool-versions

@@ -1 +1 @@
-ruby 2.6.4
+ruby 2.7.2

data/docs/README.md

@@ -1,6 +1,6 @@
 # Introduction
 
-This is unofficial documentation of the Tesla JSON API used by their iOS and Android apps. It features functionality to monitor and control their vehicle (Model S, Model X, and Model 3) and power (Powerwall) products. We currently have documentation for their vehicles, but always accept [pull requests](https://github.com/timdorr/tesla-api/pulls) for improvements and additions.
+This is unofficial documentation of the Tesla JSON API used by their iOS and Android apps. It features functionality to monitor and control their vehicle (Models S, 3, X, Y) and power (Powerwall) products. We currently have documentation for their vehicles, but always accept [pull requests](https://github.com/timdorr/tesla-api/pulls) for improvements and additions.
 
 ## Before You Begin
 

data/docs/api-basics/authentication.md

@@ -4,9 +4,129 @@ description: The authentication process for the Tesla API
 
 # Authentication
 
-## POST `/oauth/token?grant_type=password`
+> ## ⚠ This is a work in progress ⚠
+>
+> Tesla has deprecated the `/oauth/token` endpoint in favor of using `auth.tesla.com`. I'm working on updating the documentation as soon as possible. This documentation is still missing handling for MFA users. Feel free to discuss this in [issue #260](https://github.com/timdorr/tesla-api/issues/260).
 
-The initial authentication process is via [an OAuth 2.0 Password Grant](https://oauth.net/2/grant-types/password/) with the same credentials used for tesla.com and the mobile apps.
+Tesla uses a separate SSO service (auth.tesla.com) for authentication across their app and website. This service is designed around a browser-based flow using OAuth 2.0, but also appears to have support for Open ID Connect. This supports both obtaining an access token and refreshing it as it expires.
+
+## Logging in
+
+### Step 1: Obtain the login page
+
+Subsequent requests to the SSO service will require a "code challenge" and "code verifier". These are just a random 86-character string and its SHA-256 hash. Both must be encoded in base64 with url-safe encoding (base64url). Here is an example of generating them in Ruby, but you can apply this same process to other languages.
+
+```ruby
+code_verifier = random_string(86)
+code_challenge = Base64.urlsafe_encode64(Digest::SHA256.hexdigest(code_verifier))
+code_verifier = Base64.urlsafe_encode64(code_verifier)
+```
+
+You will also need a stable `state` value for requests, which is a random string of any length.
+
+#### GET `https://auth.tesla.com/oauth2/v3/authorize`
+
+The first request returns HTML intended for display in the browser. You will need to parse this HTML for hidden input fields.
+
+The request is made with a `redirect_url` of "https://auth.tesla.com/void/callback", which is a non-existent page. The Tesla app intercepts the request to this page to capture the authorization code.
+
+##### Request parameters
+
+| Field                   | Type             | Example                                | Description                                                     |
+| :---------------------- | :--------------- | :------------------------------------- | :-------------------------------------------------------------- |
+| `client_id`             | String, required | `ownerapi`                             | The OAuth client ID. Always "ownerapi"                          |
+| `code_challenge`        | String, required | `123`                                  | The "code challenge"                                            |
+| `code_challenge_method` | String, required | `S256`                                 | The code challenge hash method. Always "S256" (SHA-256)         |
+| `redirect_uri`          | String, required | `https://auth.tesla.com/void/callback` | The redirect URL. Always "https://auth.tesla.com/void/callback" |
+| `response_type`         | String, required | `code`                                 | The type of expected response. Always "code"                    |
+| `scope`                 | String, required | `openid email offline_access`          | The authentication scope. Always "openid email offline_access"  |
+| `state`                 | String, required | `123`                                  | The OAuth state value. Any random string.                       |
+
+##### Response
+
+This returns an HTML response body. There will be a `<form>` with hidden `<input>` elements that contain session-based information to prevent CSRF attacks. At the moment, they appear to be `_csrf`, `_phase`, `_process`, `transaction_id`, and `cancel`, but they may change due to server-side changes by Tesla. These must be provided in the POST body to validate the following request.
+
+The response will also include a `set-cookie` header that includes a session ID cookie. This should be provided to the following request as a `Cookie` header so that the SSO service can match up your request with private data it has in that session.
+
+### Step 2: Obtain an authorization code
+
+This will simulate a user submitting the form from the previous request in their browser. Ensure that the hidden `<input>`s are provided as POST body parameters and the `Cookie` header is set.
+
+#### POST `https://auth.tesla.com/oauth2/v3/authorize`
+
+```http
+Cookie: {cookie value from set-cookie header}
+```
+
+##### Request parameters
+
+> Note: These are query parameters, not part of the POST body
+
+| Field                   | Type             | Example                                | Description                                                     |
+| :---------------------- | :--------------- | :------------------------------------- | :-------------------------------------------------------------- |
+| `client_id`             | String, required | `ownerapi`                             | The OAuth client ID. Always "ownerapi"                          |
+| `code_challenge`        | String, required | `123`                                  | The "code challenge"                                            |
+| `code_challenge_method` | String, required | `S256`                                 | The code challenge hash method. Always "S256" (SHA-256)         |
+| `redirect_uri`          | String, required | `https://auth.tesla.com/void/callback` | The redirect URL. Always "https://auth.tesla.com/void/callback" |
+| `response_type`         | String, required | `code`                                 | The type of expected response. Always "code"                    |
+| `scope`                 | String, required | `openid email offline_access`          | The authentication scope. Always "openid email offline_access"  |
+| `state`                 | String, required | `123`                                  | The OAuth state value. Any random string.                       |
+
+> Note: This is the contents of the POST body. These should be form encoded (`application/x-www-form-urlencoded`).
+
+| Field              | Type               | Example             | Description                                       |
+| :----------------- | :----------------- | :------------------ | :------------------------------------------------ |
+| hidden input names | String[], required | hidden input values | The fields from the HTML's hidden `<input>`s      |
+| `identity`         | String, required   | `elon@tesla.com`    | The email for the authenticating Tesla account    |
+| `credential`       | String, required   | `brbgoingtomars`    | The password for the authenticating Tesla account |
+
+##### Response
+
+This will respond with a 302 HTTP response code, which will attempt to redirect to the redirect_uri with additional query parameters added. This new URL is located in the `location` header. You should not follow it, as it is non-existent. Instead, you should parse this URL and extract the `code` query parameter, which is your authorization code.
+
+### Step 3: Exchange authorization code for bearer token
+
+#### POST `https://auth.tesla.com/oauth2/v3/token`
+
+This is a standard [OAuth 2.0 Authorization Code exchange](https://oauth.net/2/grant-types/authorization-code/). This endpoint uses JSON for the request and response bodies.
+
+##### Request parameters
+
+| Field           | Type             | Example                                | Description                                                     |
+| :-------------- | :--------------- | :------------------------------------- | :-------------------------------------------------------------- |
+| `grant_type`    | String, required | `authorization_code`                   | TThe type of OAuth grant. Always "authorization_code"           |
+| `client_id`     | String, required | `ownerapi`                             | The OAuth client ID. Always "ownerapi"                          |
+| `code`          | String, required | `123`                                  | The authorization code from the last request.                   |
+| `code_verifier` | String, required | `123`                                  | The code verifier string generated previously.                  |
+| `redirect_uri`  | String, required | `https://auth.tesla.com/void/callback` | The redirect URL. Always "https://auth.tesla.com/void/callback" |
+
+```json
+{
+  "grant_type": "authorization_code",
+  "client_id": "ownerapi",
+  "code": "123",
+  "code_verifier": "123",
+  "redirect_uri": "https://auth.tesla.com/void/callback"
+}
+```
+
+##### Response
+
+```json
+{
+  "access_token": "eyJaccess",
+  "refresh_token": "eyJrefresh",
+  "expires_in": 300,
+  "state": "of the union",
+  "token_type": "Bearer"
+}
+```
+
+### Step 4: Exchange bearer token for access token
+
+#### POST `https://owner-api.teslamotors.com/oauth/token`
+
+This endpoint follows [RFC 7523](https://tools.ietf.org/html/rfc7523) to exchange a JWT access token from the SSO service for an access token usable by the Owner API.
 
 The current client ID and secret are [available here](https://pastebin.com/pS7Z6yyP).
 
@@ -18,29 +138,30 @@ Authorization: Bearer {access_token}
 
 The access token has a 45 day expiration.
 
-### Request parameters
+##### Request parameters
 
-| Field           | Type             | Example                | Description                                       |
-| :-------------- | :--------------- | :--------------------- | :------------------------------------------------ |
-| `grant_type`    | String, required | `password`             | The type of OAuth grant. Always "password"        |
-| `client_id`     | String, required | `abc`                  | The OAuth client ID                               |
-| `client_secret` | String, required | `123`                  | The OAuth client secret                           |
-| `email`         | String, required | `elon@teslamotors.com` | The email for the authenticating Tesla account    |
-| `password`      | String, required | `edisonsux`            | The password for the authenticating Tesla account |
+> Important: Ensure you are using the `access_token` from the SSO service here. The returned access_token is for all other requests to the Owner API.
 
-### Request
+```http
+Authorization: Bearer {access_token}
+```
+
+| Field           | Type             | Example                                       | Description                                                                   |
+| :-------------- | :--------------- | :-------------------------------------------- | :---------------------------------------------------------------------------- |
+| `grant_type`    | String, required | `urn:ietf:params:oauth:grant-type:jwt-bearer` | The type of OAuth grant. Always "urn:ietf:params:oauth:grant-type:jwt-bearer" |
+| `client_id`     | String, required | `abc`                                         | The OAuth client ID                                                           |
+| `client_secret` | String, required | `123`                                         | The OAuth client secret                                                       |
+
+##### Request
 
 ```json
 {
-  "grant_type": "password",
+  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
   "client_id": "abc",
-  "client_secret": "123",
-  "email": "elon@teslamotors.com",
-  "password": "edisonsux"
-}
+  "client_secret": "123"
 ```
 
-### Response
+##### Response
 
 ```json
 {
@@ -52,38 +173,44 @@ The access token has a 45 day expiration.
 }
 ```
 
-## POST `/oauth/token?grant_type=refresh_token`
+## Refreshing an access token
+
+#### POST `https://auth.tesla.com/oauth2/v3/token`
 
-You can use the `refresh_token` from the Password Grant to do [an OAuth 2.0 Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/) and obtain a new access token. Note: This will invalidate the previous access token.
+This uses the SSO `refresh_token` from Step 3 above to do an [OAuth 2.0 Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/). _This does not work with the `refresh_token` provided by the Owner API._ Those have no use currently and should be discarded.
 
-### Request parameters
+This refreshed access token can be used with the Owner API to obtain a new access token for that service using the exact same request as Step 4 above.
 
-| Field           | Type             | Example         | Description                                               |
-| :-------------- | :--------------- | :-------------- | :-------------------------------------------------------- |
-| `grant_type`    | String, required | `refresh_token` | The type of OAuth grant. Always "refresh_token"           |
-| `client_id`     | String, required | `abc`           | The OAuth client ID                                       |
-| `client_secret` | String, required | `123`           | The OAuth client secret                                   |
-| `refresh_token` | String, required | `cba321`        | The refresh token returned from a previous token request. |
+This endpoint uses JSON for the request and response bodies.
 
-### Request
+##### Request parameters
+
+| Field           | Type             | Example                       | Description                                                    |
+| :-------------- | :--------------- | :---------------------------- | :------------------------------------------------------------- |
+| `grant_type`    | String, required | `refresh_token`               | TThe type of OAuth grant. Always "refresh_token"               |
+| `client_id`     | String, required | `ownerapi`                    | The OAuth client ID. Always "ownerapi"                         |
+| `client_secret` | String, required | `123`                         | The OAuth client ID.                                           |
+| `refresh_token` | String, required | `123`                         | The refresh token from a prior authentication.                 |
+| `scope`         | String, required | `openid email offline_access` | The authentication scope. Always "openid email offline_access" |
 
 ```json
 {
-  "grant_type": "refresh_token",
-  "client_id": "abc",
+  "grant_type": "authorization_code",
+  "client_id": "ownerapi",
   "client_secret": "123",
-  "refresh_token": "cba321"
+  "refresh_token": "eyJrefresh",
+  "scope": "openid email offline_access"
 }
 ```
 
-### Response
+##### Response
 
 ```json
 {
-  "access_token": "abc123",
-  "token_type": "bearer",
-  "expires_in": 3888000,
-  "refresh_token": "cba321",
-  "created_at": 1538359034
+  "access_token": "eyJaccess",
+  "refresh_token": "eyJrefresh",
+  "id_token": "id",
+  "expires_in": 300,
+  "token_type": "Bearer"
 }
 ```

data/docs/api-basics/vehicles.md

@@ -35,7 +35,7 @@ Retrieve a list of your owned vehicles (includes vehicles not yet shipped!)
       "in_service": false,
       "id_s": "12345678901234567",
       "calendar_enabled": true,
-      "api_version": 4,
+      "api_version": 7,
       "backseat_token": null,
       "backseat_token_updated_at": null
     }
@@ -50,9 +50,9 @@ These resources are read-only and determine the state of the vehicle's various s
 
 ### URL parameters
 
-| Field | Example | Description |
-| :--- | :--- | :--- |
-| `id` | `12345678901234567` | The `id` of the car. (Not the `vehicle_id`!) |
+| Field | Example             | Description                                  |
+| :---- | :------------------ | :------------------------------------------- |
+| `id`  | `12345678901234567` | The `id` of the car. (Not the `vehicle_id`!) |
 
 ### Response
 
@@ -70,10 +70,9 @@ These resources are read-only and determine the state of the vehicle's various s
     "in_service": false,
     "id_s": "12345678901234567",
     "calendar_enabled": true,
-    "api_version": 4,
+    "api_version": 7,
     "backseat_token": null,
     "backseat_token_updated_at": null
   }
 }
 ```
-

data/docs/miscellaneous/endpoints.md

@@ -1,6 +1,6 @@
 # Endpoints File
 
-This the latest contents of the ownerapi_endpoints.json file from the 3.10.0 version of the app.
+This the latest contents of the ownerapi_endpoints.json file from the 3.10.8 version of the app.
 
 ```json
 {
@@ -329,10 +329,11 @@ This the latest contents of the ownerapi_endpoints.json file from the 3.10.0 ver
     "URI": "api/1/vehicles/{vehicle_id}/eligible_upgrades",
     "AUTH": true
   },
-  "AUTOPILOT_UPGRADE_URL": {
+  "UPGRADES_PAGE": {
     "TYPE": "GET",
-    "URI": "api/1/vehicles/{vehicle_id}/purchase_url",
-    "AUTH": true
+    "URI": "upgrades_page",
+    "AUTH": true,
+    "CONTENT": "HTML"
   },
   "MESSAGE_CENTER_MESSAGE_LIST": {
     "TYPE": "GET",
@@ -430,6 +431,12 @@ This the latest contents of the ownerapi_endpoints.json file from the 3.10.0 ver
     "URI": "api/1/energy_sites/{site_id}/site_info",
     "AUTH": true
   },
+  "ENERGY_SERVICE_SCHEDULING_PAGE": {
+    "TYPE": "GET",
+    "URI": "energy_service_scheduling_page",
+    "AUTH": true,
+    "CONTENT": "HTML"
+  },
   "HISTORY_DATA": {
     "TYPE": "GET",
     "URI": "api/1/energy_sites/{site_id}/history",
@@ -440,11 +447,26 @@ This the latest contents of the ownerapi_endpoints.json file from the 3.10.0 ver
     "URI": "api/1/energy_sites/{site_id}/calendar_history",
     "AUTH": true
   },
+  "SAVINGS_FORECAST": {
+    "TYPE": "GET",
+    "URI": "api/1/energy_sites/{site_id}/savings_forecast",
+    "AUTH": true
+  },
+  "TARIFF_RATES": {
+    "TYPE": "GET",
+    "URI": "api/1/energy_sites/{site_id}/tariff_rates",
+    "AUTH": true
+  },
   "BACKUP_RESERVE": {
     "TYPE": "POST",
     "URI": "api/1/energy_sites/{site_id}/backup",
     "AUTH": true
   },
+  "OFF_GRID_VEHICLE_CHARGING_RESERVE": {
+    "TYPE": "POST",
+    "URI": "api/1/energy_sites/{site_id}/off_grid_vehicle_charging_reserve",
+    "AUTH": true
+  },
   "SITE_NAME": {
     "TYPE": "POST",
     "URI": "api/1/energy_sites/{site_id}/site_name",

data/docs/vehicle/commands/climate.md

@@ -30,6 +30,8 @@ Stop the climate control (HVAC) system.
 
 Sets the target temperature for the climate control (HVAC) system.
 
+Note: Despite accepting two parameters, only the `driver_temp` will be used to set the target temperature. 
+
 Note: The parameters are always in celsius, regardless of the region the car is in or the display settings of the car.
 
 ### Parameters

data/docs/vehicle/commands/homelink.md

@@ -8,7 +8,7 @@ Opens or closes the primary Homelink device. The provided location must be in pr
 
 | Parameter | Example            | Description        |
 | :-------- | :----------------- | :----------------- |
-| lat       | 36.98765432109876  | Current lattitude. |
+| lat       | 36.98765432109876  | Current latitude. |
 | lon       | -77.12345678901234 | Current longitude. |
 
 ### Response

data/docs/vehicle/commands/sharing.md

@@ -4,7 +4,7 @@
 
 Sends a location for the car to start navigation or play a video in theatre mode.
 
-These docs take from the Android app, which sends the data in JSON form. However, a urlencoded POST body will work as well. The basic format to a request looks like this:
+These docs take from the Android app, which sends the data in JSON form. However, a [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding) POST body will work as well. The basic format to a request looks like this:
 
 ```json
 {
@@ -24,7 +24,7 @@ Note: This API was previously `navigation_request`, but has been updated to supp
 | Parameter                        | Example                     | Description                                                    |
 | :------------------------------- | :-------------------------- | :------------------------------------------------------------- |
 | type                             | share_ext_content_raw       | Must be `share_ext_content_raw`.                               |
-| locale                           | en-US                       | The locale for the navigation request.                         |
+| locale                           | en-US                       | The locale for the navigation request. [ISO 639-1 standard language codes](https://www.andiamo.co.uk/resources/iso-language-codes/)                        |
 | timestamp_ms                     | 1539465730                  | The current UNIX timestamp.                                    |
 | value[android.intent.extra.TEXT] | 123 Main St, City, ST 12345 | The address or video URL to set as the navigation destination. |
 

data/docs/vehicle/commands/valet.md

@@ -4,16 +4,18 @@ Valet Mode limits the car's top speed to 70MPH and 80kW of acceleration power. I
 Wifi settings, and the ability to disable mobile access to the car. It also hides your favorites, home, and work
 locations in navigation.
 
+Note: the `password` parameter isn't required to turn on or off Valet Mode, even with a previous PIN set. If you clear the PIN and activate Valet Mode without the parameter, you will only be able to deactivate it from your car's screen by signing into your Tesla account. 
+
 ## POST `/api/1/vehicles/{id}/command/set_valet_mode`
 
 Activates or deactivates Valet Mode.
 
 ### Parameters
 
-| Parameter | Example | Description                                                                       |
-| :-------- | :------ | :-------------------------------------------------------------------------------- |
-| on        | true    | true to activate, false to deactivate. Must include previous PIN if deactivating. |
-| password  | 1234    | A PIN to deactivate Valet Mode. Can be blank if activating with a previous PIN.   |
+| Parameter | Example | Description                                                                     |
+| :-------- | :------ | :------------------------------------------------------------------------------ |
+| on        | true    | true to activate, false to deactivate.                                          |
+| password  | 1234    | A PIN to deactivate Valet Mode. Please see note about the `password` parameter. |
 
 ### Response
 
@@ -26,7 +28,7 @@ Activates or deactivates Valet Mode.
 
 ## POST `/api/1/vehicles/{id}/command/reset_valet_pin`
 
-Clears the currently set PIN for Valet Mode when deactivated. A new PIN will be required when activating again.
+Clears the currently set PIN for Valet Mode when deactivated. A new PIN will be required when activating from the car screen. See the note above about activating via the API without a PIN set.
 
 ### Response