Magic links and iframe integration

Magic links allow for you to easily expose Nectar's UI to end clients to allow them to connect utility accounts. Magic links also solve two factor authentication and complex authentication workflows challenges.

While basic utility account connections that only require username and password can be connected to a company or site via the Create Basic Utility Account Connection endpoint, often utility accounts have more complicated authentication workflows. These utility accounts need to be connected via the Nectar magic link iframe. For complete documentation, see the Utility Account Connections API.

How it works

To allow your customers to connect online utility accounts, display the Nectar utility connection page with a signed magic link.

The magic link is a publicly accessible url that contains information about the company and site that is signed and encrypted by Nectar. Use the Nectar API's Create Magic Link for Company endpoint to generate the publicId and the companyMagicLinkSecret. Then you can embed this link into your website to display Nectar's utility connection page.

The url will always start with https://dash.nectarclimate.com/create-datasource/magic-link. This link can be embedded to your services or software application with a single line of code. You can also navigate to this link for debugging purposes or to manually connect accounts with complex authentication workflows.

In the magic link flow, Nectar uses advanced browser technologies to mirror a utility website securely and allow the user to login to the utility company as they woulds normally do. Once the user is logged in, Nectar securely maintains access to the session to continuously monitor updates and download historical data.

The magic link is designed with security first. The signed secret uses a 128-bit AES encryption key and only a given company's publicId is exposed. This design allows the magic link and iframe to be displayed to end clients or users that may not be authenticated on your platform.

For full documentation on magic links and utility account connections, see Utility Account Connections.

Create utility connection

Use this iframe to allow users to connect an online utility account.

Call Nectar API's Create Magic Link for Company endpoint to generate the publicId and the companyMagicLinkSecret. Then using the publicCompanyId and the companyMagicLinkSecret from the response, navigate to the following url or display it in an iframe:

https://dash.nectarclimate.com/create-datasource/magic-link/<publicId>/company/<companyMagicLinkSecret>

• <publicId> is the public id of the company that the utility account needs to be connected to. This is a secondary id that is exposed publicly in the magic link. Not to be confused with the id field of company.
• <companyMagicLinkSecret> is an encoded string containing information about the associated company and the list of sites that is signed by a 128-bit AES encryption key. Without a valid secret, the magic link will be invalid and utility accounts cannot be connected.

Then, display the iframe onto your website. Note that the Nectar works only on a desktop view currently, so similar dimensions are recommended for the iframe via a code block like the one below:

<iframe src="https://dash.nectarclimate.com/create-datasource/magic-link/<company_id>/<nectar_signed_secret>/connect"
        width="1152" height="648"
        style="border:0;">
</iframe>

Update utility connection details

Use this iframe to allow users to edit an existing utility account connection. Modify credentials, reauthenticate, or edit which sites are associated with the connection.

To display an iframe allowing users to edit the credentials of an existing utility account connection, use Create Magic Link for editing the credentials of a Utility Account Connection. Then using the publicCompanyId and the connectionMagicLinkSecret from the response, navigate to the following url or display it in an iframe:

https://dash.nectarclimate.com/create-datasource/magic-link/<publicCompanyId>/<connectionMagicLinkSecret>/edit

• <publicCompanyId> is the public id of the company that the utility account needs to be connected to. This is a secondary id that is exposed publicly in the magic link. Not to be confused with the id field of company.
• <connectionMagicLinkSecret> is an encoded string containing information about the associated company and utility account connection that is signed by a 128-bit AES encryption key. Note that this secret is different than the companyMagicLinkSecret which is generated in the previous section

Customization and white-labeling

For language-specific support and white-labeling of the iframe styling such as fonts and colors. Please get in touch with our team at [email protected].