Users link their vendor account to your app through Enode and all supported energy devices in that account are available to you. For example, if your user wishes to link an Easee charger, they will authenticate their Easee account with Enode and their charger becomes available to you.

Since the user links their vendor account you will be able to access all devices associated with that account. If the user has more than one device tied to the same account, or if they add more devices to their account at a later time, all devices will be accessible through the Enode API.

Copy linkManaging users

Copy linkCreating a user

Users are created automatically when you request a link session for a new user ID. You can provide any unique user ID, which is used to identify the user in your Enode client and connect it to any other user data you may store in your own datastore.

Copy linkLinking vendor accounts

After you’ve requested a link sessionAPI, the user provides the credentials to their vendor account and we use them to access their device data from the vendor’s API. You can list the available devices immediately.

If a user wants to link more than one vendor account you can request another link session for an existing user ID. Devices from both accounts will be combined and available from the same user ID in the API.

Copy linkAdding or removing devices

Since Enode links to a vendor account and not individual devices, it is not possible to add or remove individual devices through an Enode API endpoint. A user can however add or remove devices from their vendor account (e.g., via the vendor’s native app). When Enode notices a change in the devices available on the user’s account, we will add or remove devices accordingly, without the user having to go through a new link session. You’ll be notified via the user:{deviceType}:discovered webhooks.

If you only want to display a specific device or a subset of devices, you need to filter the device list in your application.

Copy linkHandling user credential and authorization changes

If a user's credentials change or their oAuth token becomes invalid—for example, due to a password update on the vendor app or token expiration—they may need to reauthenticate their vendor account with Enode.

The Get UserAPI endpoint shows if a user's vendor accounts need reauthentication. Additionally, you will be notified through the webhook user:credentials:invalidated as soon as our system detects a need for the user to relink their account.

When an account requires relinking, telemetry data for the user devices will not be updated. Once the user successfully updates their link, fresh data will be available again. All historical data remains intact.

Copy linkDeauthorizing or deleting users

At some point, you may want to delete a user or vendor in a variety of ways:

• Disconnect a single vendor: Our Disconnect vendorAPI endpoint removes a single vendor from the user’s account. All devices for that vendor and stored data about that vendor will be deleted.
• Deauthorize all vendors: The Deauthorize userAPI endpoint will deauthorize your user, deleting all vendor account authorizations and credentials, and invalidating any associated sessions. This will retain the user and device IDs and all other user data, so should the user link a device through Link UI again in the future, their data will be just as they left it. This endpoint is useful to stop updating data for inactive users.
• Fully delete a user: To permanently delete a user and all of their data you can use the Unlink userAPI endpoint. Please note that this is a destructive action which should be used cautiously, since it cannot be undone.

Implementing Enode user and device management in your application

Copy linkInitiate a Link UI session

The first step in connecting to a user’s devices is to initiate a Link UI session. This is handled by the Link userAPI endpoint, which returns a Link URL that gives the specified user access to link their device within 24 hours.

Copy linkConsider Link UI options

At this point, you can also specify a few different options for Link UI depending on the devices and vendors you wish to support, scopes, color scheme, and localization (see Link userAPI endpoint for more details).

Copy linkRequest the Link UI session

Keeping any additional Link UI options from the step above in mind, you can make a request to the Link user endpoint to initiate a Link UI session for your user.

curl {API_URL}/users/{USER_ID}/link \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-d '{
    "vendorType": "vehicle",
    "language": "en-US",
    "scopes": [
      "vehicle:read:data",
      "vehicle:read:location",
      "vehicle:control:charging"
    ],
    "colorScheme": "system",
    "redirectUri": "yourapp://integrations/enode"
  }'

The response contains the Link URL to use in the next step. As mentioned in the section on creating a userAPI, this request will create a user if the specified user ID does not match an existing user ID.

{
  "linkToken": "WFiMjNjZDRANThlZmIyMzMtYTNjNS00Njk...", // used by the SDK
  "linkUrl": "{YOUR_LINK_URL}" // redirect or show in in-app browser
}

Copy linkPresent Link UI to your user

You can use the resulting linkToken or linkUrl in a number of ways, depending on the frontends you support:

• Mobile applications: Pass the linkToken into our Link SDKs for iOS and Android apps
• Web applications: We recommend redirecting the user to the link URL.

For more information on these, see our docs on the various Integration Methods.

Once the Link UI flow is completed by the user, they will return to your app via your specified redirect URI. For more, view our *detailed Link UI documentation.

Copy linkHandling device capabilities and interventions

After your user has linked their device to your app, our API returns the capabilities available for that specific device. Refer to our Capabilities Table for an overview of the capabilities that are typically found for each device.

We recommend checking the capabilities object for each individual device since the capabilities of an individual device may differ from the general capabilities of that model (for instance, a 2022 model may support vehicle location while a 2017 model may not.)

Some capabilities are inherent to the hardware of the device itself (e.g. a vehicle which does not have a GPS will never be able to transmit a location). Other capabilities can be enabled through user actions, such as enabling network connectivity. The Enode API identifies what actions a user can take to enable a specific capability and we make this information available to you as an intervention.

The capabilities of a device may change over time, for example if a device receives a software update. These get reflected in the API and you will be sent webhook events about capabilities changes. When they change, show a warning in your app to prompt your user to take action.

Depending on your needs and preferred UX, you can decide to show and use interventions in different ways:

• Show instructions immediately after linking
• Show instructions when the user tries to access specific functionality that require e.g. location data

Copy linkRelinking a vendor account

When an external event prevents Enode from accessing updated data, the connection is marked invalid. Devices will be unavailable on the API until the account is linked again using Link UI. You will receive information that they need to relink in two ways:

1. A webhook user:credentials:invalidated is delivered as soon as we know their account needs relinking. The webhook body contains the user ID and the vendor name.
2. The Get UserAPI endpoint has a list of vendor accounts each user has linked. If the isValid flag is false, the user needs to reauthenticate.

We recommend sending a push notification and/or showing a warning in the app when a vendor connection is invalid. When the user wants to relink, you can use the vendor property to request a link session for that specific vendor.