onstarjs2

OnStarJS (OnStarJS2)

An unofficial NodeJS library to make OnStar requests. This version has been forked from samrum/OnStarJS and includes the new TOTP login mechanism and support for the v3 API implemented by metheos.

Published as OnStarJS2 at https://www.npmjs.com/package/onstarjs2

Use at your own risk. This is an unofficial library.

Prerequisites

This library requires chromium-bidi to be installed and available in your environment.

Usage

Use the Get Account Vehicles request to see which requests your vehicle supports if you don't already know.

New Requirement as of 2024-11-19

Updated to use TOTP to fulfill new authentication process from GM.

You will need to change your OnStar account's MFA method to "Third-Party Authenticator App"

The "Third-Party Authenticator App" option doesn't seem to show up on mobile, so please try from a desktop browser.

You will need to capture your TOTP key from the "Third-Party Authenticator App" setup so that you can provide it in your .env or initialization config.

You may be able to obtain your TOTP key by inspecting/hovering over the link under the QR code when you are setting it up.

If you use an authenticator app such as Stratum, Bitwarden, or Vaultwarden that allows you to view your TOTP key, you can view it at any time.

In the IOS Passwords app you can tap "Copy Setup URL" and obtain the secret from the copied data.

If you cannot find the option to configure a "Third-Party Authenticator App" on your GM account page, try contacting OnStar to see if there is another way to enable it.

If that fails, use: this Windows exe or this web app

for email TOTP and then save the resulting token and provide the token location for use with https://github.com/BigThunderSR/onstar2mqtt and/or https://github.com/BigThunderSR/homeassistant-addons-onstar2mqtt.

Additional comments are noted in this issue comment.

IMPORTANT: Valid system time is required for this process to work. Please ensure that your system (Docker host, Home Assistant etc.) time is valid using a mechanism such as NTP or Chrony before attempting to use the token authentication process.

Sample

Use a random version 4 uuid as a deviceId. Generator available at this link.

import OnStar from "onstarjs";

const onStar = OnStar.create({
  deviceId: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  vin: "1G2ZF58B774109863",
  username: "[e-mail]",
  password: "p@ssw0rd",
  onStarPin: "1234",
  onStarTOTP: "XXXXXXXXXXXXXXXX",
});

try {
  await onStar.alert({
    action: ["Flash"],
  });

  await onStar.start();
} catch (e) {
  console.error(e);
}

Additional Configuration Options

checkRequestStatus

Default Value: true

When false, requests resolve when the API returns an 'In Progress' response. For requests that return data, this option is ignored.

This is useful because, with the usual request polling to wait for a "Complete" response from the API, requests will take much longer to resolve.

requestPollingIntervalSeconds

Default Value: 6

When checkRequestStatus is true, this is how often status check requests will be made (in seconds)

requestPollingTimeoutSeconds

Default Value: 90

When checkRequestStatus is true, this is how long a request will make subsequent status check requests before timing out (in seconds)

Responses

For commands that return data like diagnostics or location, the data returned by the API is accessible via result.response.data

Commands

Action Command API Compatibility

Action commands (start, cancel start, lock/unlock doors and trunk, alert, cancel alert, flash lights, and stop lights) automatically use the latest API version (v3) and will fall back to the legacy API (v1) if the vehicle doesn't support the newer version. This ensures compatibility across all vehicle types (ICE, Hybrid, and EV) without requiring manual configuration.

The library caches which API version works for your vehicle in memory during the session to optimize subsequent requests.

Get Account Vehicles

Returns a list of all vehicles associated with your OnStar account, including VINs, make, model, year, and OnStar account status.

onStar.getAccountVehicles();

Get Vehicle Details

Returns detailed vehicle information including make, model, year, RPO codes, permissions, available vehicle commands, colors, metadata, and OnStar account info.

onStar.getVehicleDetails([vin]);

Option	Default	Valid Values
vin	Configured VIN	Any valid VIN

Get OnStar Plan

Returns OnStar subscription plan information including offers, active plans, orders, plan expiry info, and OnStar account status (status, owner account, shared flag).

Note: Plan detail fields (planInfo, planExpiryInfo, activePlans, orders, offers) are only populated for primary account holders. Shared accounts will receive onstarInfo with the active status but plan details will be empty or trigger partial errors that are handled gracefully.

⚠️ Changes in v2.16.0:

• Fixed offers field names — The offers sub-fields have been corrected to match the current API schema (productCode, offerName, associatedOfferingCode, retailPrice, billingCadence, productRank). The previous sub-fields (offerId, expirationDate, category) no longer exist in the API.
• Partial error tolerance — Previously, any GraphQL error in the response caused the method to throw. Now, if vehicleDetails data is present alongside errors (e.g. shared accounts where offers fail), the method returns the partial data with a warning instead of throwing.
• New fields added — onstarInfo, activePlans, and orders are now included in the response. These are additive and non-breaking.

onStar.getOnstarPlan([vin]);

Option	Default	Valid Values
vin	Configured VIN	Any valid VIN

Get Vehicle Recall Info

Returns vehicle recall information including recall status, repair status, descriptions, and completion dates.

onStar.getVehicleRecallInfo([vin]);

Option	Default	Valid Values
vin	Configured VIN	Any valid VIN

Get Warranty Info

Returns vehicle warranty information including warranty types (powertrain, bumper-to-bumper, corrosion, emissions, etc.), coverage dates, mileage limits, and current status.

onStar.getWarrantyInfo([vin]);

Option	Default	Valid Values
vin	Configured VIN	Any valid VIN

Get SXM Subscription Info

Returns SiriusXM satellite radio subscription information including device ID, subscription status, channel account details, and deactivation info.

onStar.getSxmSubscriptionInfo([vin]);

Option	Default	Valid Values
vin	Configured VIN	Any valid VIN

Diagnostics

Returns comprehensive vehicle diagnostics including odometer, tire pressure, fuel economy, battery levels, and other vehicle health information.

Note: The v3 API automatically returns all available diagnostic data. The previous diagnosticItem options parameter from the v1 API is no longer supported.

onStar.diagnostics();

Location

Returns the vehicle's current location.

onStar.location();

Example Response

{ "location": { "lat": "50", "long": "-75" } }

Start

Starts the vehicle's engine remotely.

onStar.start();

Cancel Start

Cancels a remote start command that is currently active.

onStar.cancelStart();

Alert

Triggers the vehicle's alerts remotely by flashing lights and/or honking the horn.

onStar.alert([options]);

Option	Default	Valid Values
action	["Flash", "Honk"]	["Flash", "Honk"]
delay	0	Any integer (minutes)
duration	1	Any integer (minutes)
override	["DoorOpen", "IgnitionOn"]	["DoorOpen", "IgnitionOn"]

Cancel Alert

Cancels an active alert command.

onStar.cancelAlert();

Flash Lights

Flashes the vehicle's lights remotely without honking the horn.

onStar.flashLights([options]);

Option	Default	Valid Values
delay	0	Any integer (minutes)
duration	1	Any integer (minutes)
override	["DoorOpen"]	["DoorOpen", "IgnitionOn"]

Stop Lights

Stops an active flash lights command.

onStar.stopLights();

Lock Door

Locks all the vehicle's doors remotely.

onStar.lockDoor([options]);

Option	Default	Valid Values
delay	0	Any integer (minutes)

Unlock Door

Unlocks all the vehicle's doors remotely.

onStar.unlockDoor([options]);

Option	Default	Valid Values
delay	0	Any integer (minutes)

Lock Trunk

Locks the vehicle's trunk remotely but doesn't automatically close it.

onStar.lockTrunk([options]);

Option	Default	Valid Values
delay	0	Any integer (minutes)

Unlock Trunk

Unlocks the vehicle's trunk remotely but doesn't automatically open it. All doors remain locked.

onStar.unlockTrunk([options]);

Option	Default	Valid Values
delay	0	Any integer (minutes)

Get EV Charging Metrics

Returns current EV charging metrics and status information for electric vehicles.

onStar.getEVChargingMetrics([options]);

Option	Default	Valid Values
clientVersion	"8.5.0.8060"	Any version string
os	"a"	"a" (Android), "I" (iOS)

Refresh EV Charging Metrics

Returns fresh EV charging metrics and status information for electric vehicles. Unlike getEVChargingMetrics() which retrieves existing data, this method forces the vehicle to generate updated telemetry before returning.

onStar.refreshEVChargingMetrics([options]);

Option	Default	Valid Values
clientVersion	"8.5.0.8060"	Any version string
os	"a"	"a" (Android), "I" (iOS)

Set Charge Level Target

Sets the target charge level percentage for electric vehicles.

onStar.setChargeLevelTarget(tcl, [options]);

Option	Default	Valid Values
tcl	(required)	0-100 (percentage)
noMetricsRefresh	false	true, false
clientRequestId	auto-generated	Any UUID string
clientVersion	"8.5.0.8060"	Any version string
os	"a"	"a" (Android), "I" (iOS)

Stop Charging

Stops the current charging session for electric vehicles.

onStar.stopCharging([options]);

Option	Default	Valid Values
noMetricsRefresh	false	true, false
clientRequestId	auto-generated	Any UUID string
clientVersion	"8.5.0.8060"	Any version string
os	"a"	"a" (Android), "I" (iOS)

⚠️ Charge Override (Deprecated)

Deprecated: This v1 API method is no longer available. Use setChargeLevelTarget() and stopCharging() instead for EV charging control.

// DEPRECATED - Do not use
onStar.chargeOverride([options]);

⚠️ Get Charging Profile (Deprecated)

Deprecated: This v1 API method is no longer available. Use getEVChargingMetrics() instead to retrieve current charging information.

// DEPRECATED - Do not use
onStar.getChargingProfile();

⚠️ Set Charging Profile (Deprecated)

Deprecated: This v1 API method is no longer available. Use setChargeLevelTarget() instead to configure EV charging settings.

// DEPRECATED - Do not use
onStar.setChargingProfile([options]);

Development

• Clone this repository
• Install latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install

Tests

All

Run both unit and functional tests.

pnpm test

Unit

pnpm test:unit

Auth

pnpm test:auth

Reauth

Tests the re-authentication flow by simulating expired tokens and browser reinitialization scenarios. This is particularly useful for testing long-running applications that need to re-authenticate periodically.

pnpm test:reauth

Functional

These tests will execute actual requests to the OnStar API. They will perform a Get Account Vehicles request followed by a Cancel Alert request and then a Diagnostics request.

Because of this, the test will require actual OnStar credentials to run. To provide them, copy .env.example to .env and replace the placeholder values inside.

pnpm test:functional

Credits

• mikenemat's gm-onstar-probe - Their work describing the process for remote start enabled the rest of the methods implemented here
• samrum/OnStarJS - Original OnStarJS implementation
• metheos - New GMAuth functionality, TOTP authentication implementation, and v3 API support