Skip to main content
For platform users: See the Magic Links overview to understand the end-user experience.
Magic links let you expose Nectar’s utility connection UI to your end users. They handle two-factor authentication and complex login workflows that can’t be completed through a basic API call.

​
How it works

  1. You call the Nectar API to generate a magic link containing a publicId and a companyMagicLinkSecret.
  2. You construct a URL from those two values and display it to your user — either as a direct link or embedded in an iframe.
  3. The user connects their utility account through Nectar’s secure interface, which mirrors the utility provider’s login flow.
  4. Nectar maintains secure access to the session to continuously download historical and new data.
The magic link is publicly accessible by design. The signed secret uses 128-bit AES encryption, and only the company’s publicId is exposed — meaning the link is safe to display to unauthenticated end users.
1

Generate the magic link

Call the create magic link endpoint for the target company. The response contains publicId and companyMagicLinkSecret.
curl -X POST 'https://external.nectarclimate.com/v2.2/company/{companyId}/connection/link' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "sites": ["{siteId}"]
  }'
2

Construct the URL

Build the magic link URL from the response values:
https://dash.nectarclimate.com/p/connect/{publicId}/{companyMagicLinkSecret}
ParameterDescription
publicIdPublic ID of the company (not the same as the company id field)
companyMagicLinkSecretEncrypted string containing company and site information, signed with a 128-bit AES key
The /p/ prefix indicates this is a public (unauthenticated) page. Old URLs using /create-datasource/magic-link/ are automatically redirected.
3

Embed in an iframe

Display the magic link in your application. Nectar’s connection UI currently requires desktop-sized dimensions.
<iframe
  src="https://dash.nectarclimate.com/p/connect/{publicId}/{companyMagicLinkSecret}"
  width="1152"
  height="648"
  style="border: 0;"
></iframe>

​
Update an existing connection

To let users edit credentials, reauthenticate, or change which sites are associated with an existing connection, generate an edit magic link.
1

Generate the edit magic link

Call the update magic link endpoint for the existing connection. The response contains publicCompanyId and connectionMagicLinkSecret.
curl -X POST 'https://external.nectarclimate.com/v2.2/company/{companyId}/connection/{connectionId}/link' \
  -H 'X-API-Key: YOUR_SECRET_KEY'
2

Construct the edit URL

The edit URL uses the /workflow/ path segment and the connection-specific secret:
https://dash.nectarclimate.com/p/connect/{publicCompanyId}/workflow/{connectionMagicLinkSecret}
ParameterDescription
publicCompanyIdPublic ID of the company
connectionMagicLinkSecretEncrypted string specific to this connection (different from companyMagicLinkSecret)
3

Embed the edit iframe

<iframe
  src="https://dash.nectarclimate.com/p/connect/{publicCompanyId}/workflow/{connectionMagicLinkSecret}"
  width="1152"
  height="648"
  style="border: 0;"
></iframe>

​
Prefilling data

You can pre-populate information in the magic link form — including the utility provider URL, data collection start date, and sites — by passing additional fields when generating the magic link. This data is encoded in the companyMagicLinkSecret, keeping it secure. See the create magic link endpoint in the API Reference for the full list of prefill parameters.

​
Customization

Nectar supports white-label branding of the magic link iframe, including custom fonts, colors, and language localization. See the White-label documentation or contact [email protected] for setup details.

​
Security

The magic link secret uses 128-bit AES encryption. Only the company’s publicId is exposed in the URL — no internal IDs, credentials, or sensitive data are transmitted in plaintext. This design allows the magic link to be safely displayed to end users who are not authenticated on your platform.

​
Next steps

Sandbox testing

Test the magic link flow with mock data

Webhooks

Get notified when a connection is created or updated

Connection statuses

Understand the connection lifecycle