# User and device lifecycle

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.

## Managing users

### Creating a user

Users are created automatically when you [request a link session](https://developers.enode.com/docs/integration-guide/user-device-lifecycle) 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.

### Linking vendor accounts

After you’ve [requested a link session](https://developers.enode.com/api/reference#postUsersUseridLink), 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.

### Adding 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.

### Handling 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 User](https://developers.enode.com/api/reference#getUser) 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.

### Deauthorizing 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 vendor](https://developers.enode.com/api/reference#disconnectUserVendor) 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 user](https://developers.enode.com/api/reference#deleteUsersUseridAuthorization) 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 user](https://developers.enode.com/api/reference#deleteUsersUserid) 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

### Initiate a Link UI session

Link UI: Review our [Link UI guide](https://developers.enode.com/docs/link-ui/introduction) for screenshots and a more detailed guide to linking and the options available to you.

The first step in connecting to a user's devices is to initiate a Link UI session. This is handled by the [Link user](https://developers.enode.com/api/reference#postUsersUseridLink) endpoint, which returns a Link URL that gives the specified user access to link their device within 24 hours.

#### Consider 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 user](https://developers.enode.com/api/reference#postUsersUseridLink) endpoint for more details).

#### Request 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](https://developers.enode.com/api/reference#postUsersUseridLink) endpoint to initiate a Link UI session for your user.

```bash {% title="Link UI session request example" %}
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 user](https://developers.enode.com/api/reference#postUsersUseridLink), this request will create a user if the specified **user ID** does not match an existing user ID.

```json {% title="Link UI session response example" %}
{
  "linkToken": "WFiMjNjZDRANThlZmIyMzMtYTNjNS00Njk...", // used by the SDK
  "linkUrl": "{YOUR_LINK_URL}" // redirect or show in in-app browser
}
```

### Present 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](https://developers.enode.com/docs/link-sdks/introduction) 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](https://developers.enode.com/docs/link-ui/introduction#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](https://developers.enode.com/docs/link-ui/introduction).

## Handling device capabilities and interventions

Interventions: Review our [Interventions](https://developers.enode.com/docs/interventions) for a more detailed reference of 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 [brands overview](https://developers.enode.com/brands) 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](https://developers.enode.com/docs/interventions).

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

## Relinking 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. Upon recieving this webhook, we recommend sending a push notification to your user to inform them that their vendor account needs to be relinked.
2. The asset data will contain an intervention with a `Link` action. Every time you display a device in your app, you should check if any of the interventions on the device have the `resolution.action` property set to `Link`. If so, you should display display a button to trigger a relinking session. Please refer to our [relinking guide](https://developers.enode.com/docs/link-ui/relinking) for more details.