> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nectarclimate.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MFA integration
> How to help end customers get data flowing when their utility portal requires multi-factor authentication — ordered from lowest-effort to highest-effort.
**For platform users:** See the [MFA overview](/platform/data-input/mfa) for end-user guidance
and [utility-specific guides](/platform/data-input/mfa#utility-specific-guides) for step-by-step
instructions per provider.
Some utility portals require a second verification step (a code sent by email or SMS, an authenticator app, or a security question) on every login. Because automated logins run on Nectar's schedule — not the end customer's device — Nectar needs a way to receive those codes too.
This page is the decision tree you and your customer support team should work through when an end customer's utility portal requires MFA. It is ordered from the path that causes the fewest support tickets to the one that causes the most.
## Recommendation ladder
When a connection needs MFA — at onboarding, or after the status transitions to `MFA_TOKEN_EXPIRED` — present these options to the end customer **in this order**:
| # | Option | What it asks the customer to do | Recommended when |
| - | ----------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Upload documents** | Email or upload PDF bills; nothing on the utility portal changes. | Always the first option. Works for any portal and requires no account changes. |
| 2 | **Disable MFA on the portal** | Turn off MFA in the utility portal's account settings, if the portal allows it. | Customer controls the utility account and their organization's policies permit it. |
| 3 | **Managed MFA forwarding** | Change the utility portal's MFA destination to a Nectar-provided email address. | Customer must keep MFA on and is comfortable setting a third-party email as the code destination. |
| 4 | **Customer-inbox forwarding** | Keep the utility's existing MFA email; set up auto-forwarding from that inbox to Nectar. | Customer cannot change the portal's MFA destination. Frequently fails because of corporate email security policies. |
| 5 | **SMS MFA relay** *(beta)* | Change the utility portal's MFA phone number to a Nectar-provided number. | Portal only supports SMS MFA and email options are off the table. [Contact support](mailto:support@nectarclimate.com) to request access. |
**Recommend options 1 and 2 before any forwarding strategy.** Most end customers push back on
options 3–5 because they require changing utility portal settings or routing codes to a third
party, and option 4 silently fails on corporate email systems with external-forwarding
restrictions (M365 / Google Workspace DLP rules, connector policies, etc.). Upload and disable-MFA
avoid both problems entirely.
## 1. Upload documents
Direct the end customer to upload their utility bill PDFs. The parsed output — documents, meters, accounts, and usage data — is identical to what automated collection produces, and no portal or email configuration is required.
Upload bills through the API with [`POST /job/company/{companyId}/bulk`](/developer-guide/document-upload), or have your end customer drag PDFs into the Nectar app.
Choose this first when:
* The end customer is a facility manager who already receives bills by email.
* The portal's MFA cannot be disabled and the customer will not change its destination.
* You need historical data quickly — uploading a batch of PDFs is faster than waiting for a weekly automated pull.
See [Document upload](/developer-guide/document-upload) for the full endpoint reference.
## 2. Disable MFA on the portal
Many utility portals make MFA optional. If the end customer controls the account and their organization allows it, turning MFA off in the portal's security settings is the simplest way to restore fully automated weekly collection with no ongoing forwarding to maintain.
After the customer disables MFA on the portal, use a [reconnect invitation](/developer-guide/connection-invitations#create-a-reconnect-invitation) to refresh the stored credentials. Nectar picks up the new login on the next scheduled check.
Choose this when:
* The utility portal's security settings allow turning off MFA.
* Organizational policy does not require MFA on utility accounts.
## 3. Managed MFA forwarding (recommended forwarding strategy)
Nectar provisions a unique email address for the connection. The end customer sets that address as the MFA destination in the utility portal's account settings. When the portal sends a login code, Nectar receives it directly and uses it to complete the automated login. Nectar can also auto-forward the raw code to any additional email addresses the customer specifies, so the customer continues to see their codes.
Use this when the customer must keep MFA on, can change the portal's MFA destination, and doesn't want to manage their own forwarding rules.
**How the end customer configures it:**
The Nectar-hosted wizard displays the dedicated email address for this connection.
In the portal's account or security settings, set the Nectar-provided email as the MFA code
destination.
In the Nectar wizard, list any customer-side emails that should also receive a copy of each
code.
Nectar triggers a test login and waits for the code. Once received, the connection transitions
back to `CONNECTED`.
**Why this is the recommended forwarding strategy:**
* Nectar receives codes directly from the utility portal — no dependency on the customer's email infrastructure.
* No email-forwarding rules for the customer to maintain.
* The same setup flow works for managed-service customers whose own IT team has to approve the change.
**Friction to flag to the end customer up front:**
* They will need access to the portal's MFA settings.
* They must be comfortable setting a third-party email as the MFA destination.
## 4. Customer-inbox forwarding
The customer keeps their existing MFA email on the utility portal and adds an auto-forwarding rule in their own inbox that forwards the utility's MFA emails to a Nectar-provided address.
Use this only when the customer cannot or will not change the MFA destination on the utility portal.
**This strategy fails frequently.** Corporate email providers routinely block external
auto-forwarding through tenant-wide policies (Microsoft 365 anti-spoofing rules, Google Workspace
DLP, connector restrictions, mail-flow rules). When forwarding is silently disabled, Nectar stops
receiving codes and the connection transitions back to `MFA_TOKEN_EXPIRED` — often without the end
customer noticing. If the customer is on a managed work email account, steer them to option 1, 2,
or 3 first.
**How the end customer configures it:**
The reconnect wizard displays a unique forwarding address. The customer adds a filter in their email client that auto-forwards messages from the utility's MFA sender to that address. Guidance for the most common providers is included in the [shareable one-pager](#shareable-one-pager) at the bottom of this page.
**Common failure modes your support team should recognize:**
* Admin policy blocks external auto-forwarding (the filter saves but never fires).
* The utility rotates the sender address used for codes and the filter's sender match goes stale.
* A forwarding rule is disabled automatically after a suspicious-login event.
## 5. SMS MFA relay (beta)
For utility portals that only support phone-based MFA, Nectar can provision a phone number that receives SMS codes. The customer sets that number as the MFA destination in the portal; Nectar captures each code and can relay it to customer-owned phone numbers.
This capability is currently in limited beta.
**Beta access:** Email [support@nectarclimate.com](mailto:support@nectarclimate.com) with the
company name and the utility portals that require SMS MFA. We will enable the capability on your
organization and walk your team through the setup flow.
The end-customer friction is similar to managed MFA forwarding (option 3): the customer must change the portal's MFA destination to a Nectar-provided number, which some customers will not agree to.
## Detecting MFA issues from the API
Subscribe to [`connection.updated.v2` webhooks](/developer-guide/webhooks#connection-updated-v2) and branch on `status`:
```ts theme={null}
// Pseudocode for your webhook handler
if (event.eventType === 'connection.updated.v2' && event.status === 'MFA_TOKEN_EXPIRED') {
// Present the recommendation ladder to the account owner.
// In order: upload documents, disable MFA, managed forwarding, inbox forwarding, SMS relay (beta).
await notifyAccountOwner(event.id, event.datasource.name);
await createReconnectInvitation(event.id, { allowedEmails: [event.ownerEmail] });
}
```
When the customer completes whichever path they choose, a follow-up `connection.updated.v2` event fires with `status: "CONNECTED"`.
See [Connection lifecycle — credential errors](/developer-guide/connection-lifecycle#credential-errors-user-action-required) for the full set of statuses that stop collection.
## Triage flow for customer support teams
When an end customer reports a broken MFA connection, walk through these questions in order. The first "yes" determines the path.
1. **Can the customer upload bills instead?** → Route to [Document upload](/developer-guide/document-upload). Stop here for most cases.
2. **Can the customer disable MFA on the utility portal?** → Have them disable it, then send a reconnect invitation.
3. **Will the customer change the portal's MFA destination to a Nectar email?** → Managed MFA forwarding.
4. **Is the customer on a personal / unrestricted email account?** → Customer-inbox forwarding may work.
5. **Portal only supports SMS?** → Request SMS MFA relay beta access.
## Shareable end-user guide
Need to send MFA guidance to an end customer? Link them to the [Multi-factor authentication (MFA)](/platform/data-input/mfa) page — it covers all options, utility-specific setup guides, and troubleshooting in a customer-friendly format. You can also link directly to the [triage flow](/platform/data-input/mfa#triage-flow-fixing-an-mfa-connection) or the [options summary table](/platform/data-input/mfa#options-summary).
## Related pages
End-user MFA guide with utility-specific setup instructions.
Submit bills directly — the recommended first option for MFA-protected accounts.
Create reconnect invitations that open the MFA wizard for end customers.
Detect `MFA_TOKEN_EXPIRED` via webhooks and trigger the recovery flow.