Skip to main content
For platform users: See Reconnecting for the in-app reconnect wizard.
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:
#OptionWhat it asks the customer to doRecommended when
1Upload documentsEmail or upload PDF bills; nothing on the utility portal changes.Always the first option. Works for any portal and requires no account changes.
2Disable MFA on the portalTurn 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.
3Managed MFA forwardingChange 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.
4Customer-inbox forwardingKeep 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.
5SMS 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 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, 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 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 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.
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:
1

Start a reconnect (or complete the initial connection flow)

The Nectar-hosted wizard displays the dedicated email address for this connection.
2

Sign in to the utility portal

In the portal’s account or security settings, set the Nectar-provided email as the MFA code destination.
3

Optionally add additional recipients

In the Nectar wizard, list any customer-side emails that should also receive a copy of each code.
4

Confirm

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 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 [email protected] 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 and branch on status: 
// 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 for the full set of statuses that pause 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. 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 one-pager

The section below is written for end customers. You can paste it into your own help center, forward it in an email, or link directly (use /developer-guide/mfa-integration#shareable-one-pager).

​
Your utility portal uses MFA — here’s how to keep data flowing

Your utility portal requires a second step to log in (an emailed code, a text message, or an authenticator app). Automated utility data collection can’t complete that step on its own, so we offer several options. Pick the first option that works for you. Each one further down takes more effort to maintain.
Email us your utility bill PDFs, or drag them into the upload area. We extract the same data as an automated connection — usage, costs, meter details — without touching your utility portal. No MFA configuration required.Best for: Most customers. Facility managers who already receive bills by email. Customers whose IT team won’t allow portal or email changes.
Many utility portals make MFA optional. Sign in to your utility portal’s account or security settings and turn MFA off. Once it’s off, click Reconnect in your Nectar app to resume automated collection.Best for: Customers who own the utility account and whose organization doesn’t mandate MFA on utility portals.
Keep your existing MFA email on the utility portal, then add a filter in your own inbox that auto-forwards utility MFA emails to an address we provide.Best for: Customers on personal email accounts who can’t change the portal’s MFA destination.Heads up: Most corporate email systems (Microsoft 365, Google Workspace) block auto-forwarding to external addresses by default. If your IT team enforces these rules, this option often fails silently after a few days. If you’re on a work email, try options 1–3 first.Setup guides: Gmail → Settings → Filters and blocked addresses → Create filter. Outlook / Microsoft 365 → Rules → Create rule. iCloud → Mail → Preferences → Rules. Your IT team may need to allow-list our forwarding domain.
If your utility portal only supports text-message codes, contact [email protected]. We can provision a phone number that receives your MFA texts and relay codes to phone numbers you choose. This feature is in limited beta.
Not sure which to pick? Start with option 1 — uploading bills works for everyone and takes about a minute per bill.

Document upload

Submit bills directly — the recommended first option for MFA-protected accounts.

Connection invitations

Create reconnect invitations that open the MFA wizard for end customers.

Connection lifecycle

Detect MFA_TOKEN_EXPIRED via webhooks and trigger the recovery flow.