Authentication
When you choose an API delivery mode, Nectar supports two authentication methods for connecting to the Watershed API:OAuth 2.0 (recommended)
OAuth 2.0 is Watershed’s enterprise-grade authentication standard. It uses short-lived access tokens instead of a static API key, reducing risk if credentials are compromised. To set up OAuth 2.0:- Log in to the Watershed portal and navigate to the API section under Organization settings.
- Click Create credentials to generate a new Client ID and Client Secret.
- Give the client a name, assign a role, and set the token expiration. In Nectar’s credentials step, set token expiration to 86400 seconds and grant admin access.
- Save the Client Secret securely — Watershed will not display it again.
- In Nectar, go to Data Export > Integrations > Watershed and choose OAuth 2.0 as the authentication mode.
- Enter the Client ID and Client Secret. Nectar handles token exchange and renewal automatically.
/oauth/token endpoint with grant_type=client_credentials. Tokens are refreshed automatically before expiration — Watershed does not use refresh tokens.
Watershed lets you set token lifetime in minutes. Nectar recommends 86400 seconds (24 hours) when configuring credentials for this integration.
Bearer Token (legacy)
Static long-lived API keys. This method is simpler to configure but less secure — if the key is compromised, it remains valid until manually rotated. To set up a Bearer Token:- Generate a Bearer Token API key in the Watershed portal under Organization settings > API.
- In Nectar, choose Bearer Token (API key) as the authentication mode and paste the key.
Regional endpoints
Nectar supports both Watershed API regions:
Select the region that matches your Watershed organization during setup. The same credentials work regardless of region — only the API endpoint differs.
Setup
Navigate to Data Export > Integrations > Watershed and complete setup from Settings > Company > Integrations > Watershed or the setup wizard when prompted. Steps include:- Delivery mode — Choose OAuth 2.0, API key (Bearer Token), or File download, and select your Watershed region when using an API mode. File download skips credential and dataset steps and is ready for XLSX exports immediately.
- Credentials and connection test (API modes) — Enter OAuth or Bearer credentials. Nectar validates them by fetching available datasets from Watershed.
- Dataset selection (API modes) — Choose which upload schemas to use for electricity, gas, and water when enabled.
- Site mapping (API modes) — Map Nectar sites to Watershed building identifiers (include or exclude each site).
Integration hub
The Watershed integration page at Data Export > Integrations > Watershed is a single-page layout:- Page header — Archive (deactivate the integration) and Settings (credentials, site mapping, datasets)
- Warning banners — Invalid credentials, unconfigured sites, excluded sites, or disabled data sources block API push until resolved in settings
- Status card — Connected, File export only, or setup warnings, with an Export button that opens the export dialog. In API mode, the card also shows the auto-sync status
- Recent syncs & downloads — Latest Watershed exports and API pushes. Click a sync row to open the upload detail page; click a download row for the export detail sheet
- Data comparison — When API push is fully enabled, month-by-month Nectar vs Watershed usage with discrepancy statuses (same scope as the upload detail comparison)
Exporting
Click Export to open the export dialog, then either push to Watershed or download an XLSX:- Push — Enable Push to Watershed API and select a measurement project. The dialog shows the project’s measurement period, its Utilities task, and the Nectar uploads the push will replace. A push has no date range, site, or data source selection; see What a push sends.
- File download — Choose the reporting period, sites, and data sources, and download an XLSX for manual upload in Watershed.
What a push sends
Every push, manual or scheduled, sends all of the company’s Nectar data for every mapped site and configured data source, and replaces the earlier Nectar uploads in that measurement project. Watershed only counts months inside the project’s measurement period. Only sites mapped to a Watershed building are pushed, and months with no data are sent as 0. A push is blocked when the project is closed, when its Utilities task is in review or approved, or when the project doesn’t have exactly one Utilities task. Only one push per project can run at a time.Scheduled syncs
To keep a measurement project up to date automatically, set up a Watershed sync in Settings > Personal > Scheduled tasks. A sync runs weekly or monthly and pushes the same way as a manual push. Only company admins can see and manage syncs. A company can have several syncs, but only one per measurement project, and each needs a name. See Scheduled tasks.Recent syncs & downloads
The history card lists your latest Watershed exports and API pushes. Click a sync row to open the upload detail page. Click a download row to open the export detail sheet with configuration and a re-download link. Use Data Export > History for the full cross-integration log.Data comparison — find and resolve discrepancies
When API push is fully configured, the Data comparison section on the hub reconciles what Watershed holds against your Nectar data. Use it to find discrepancies. There are no inline Push/Sync buttons; to correct Watershed, run a new push. How to use it:- Set the scope with the filters:
- Year (required) — The comparison always covers one calendar year; clearing it resets to the current year.
- Utility type — Electricity, gas, or water. Only the utility types enabled for your integration appear. Water uploads include potable and reclaimed supply only — sewer and wastewater discharge are not sent to Watershed.
- Sites — Narrow to specific mapped sites. Only sites actively mapped to a Watershed building participate.
- Datasets — Choose which Watershed uploads to count. All submitted and validated uploads are selected by default.
- Read the usage chart — Nectar and Watershed monthly totals are plotted side by side. Click a month to open the aggregation inspector for the selected sites and commodity — this shows exactly which Nectar bills and meters make up that month’s total, so you can see why the two sides differ.
- Scan the monthly comparison table — Each row shows the month, Nectar value, Watershed value, the percentage difference (red = Watershed lower, amber = Watershed higher), and a status.
- Synced — Watershed matches your data for that month
- Diff — Both sides have data but the values differ
- Not on Watershed — Nectar has data Watershed never received
- Missing in Nectar — Watershed holds a value your data no longer produces
- Use the month click → aggregation inspector to confirm whether the gap is a Nectar data issue (missing or flagged bills) or a stale Watershed upload.
- If Nectar is wrong, fix the bills in Data Inventory.
- Push to the measurement project again, or wait for the next scheduled sync.
Upload detail page
Click a sync in the recent history card to open the upload detail page. It includes:- Upload header — Name, status, and date
- Comparison view — Nectar vs Watershed data for the upload’s scope
- Contributing data — Bills and meters that were included in the upload
Data format
Nectar sends aggregated monthly utility usage to Watershed. Electricity and gas records commonly include:
When water is enabled for your integration, Nectar also sends water usage to Watershed. Water uploads include potable and reclaimed supply only — sewer and wastewater discharge are not sent.
FAQ
How does Nectar map sites to Watershed buildings?
How does Nectar map sites to Watershed buildings?
Nectar matches sites to Watershed using the site mapping you configure during setup. Go to the Watershed integration settings to map each Nectar site to its corresponding Watershed building identifier.
How do I correct data already in Watershed?
How do I correct data already in Watershed?
Fix the data in Nectar, then push to the measurement project again. Each push replaces the earlier Nectar uploads in that project, so you don’t need to delete anything in Watershed.
Can I push only some months, sites, or data sources?
Can I push only some months, sites, or data sources?
No. Every push sends all data for every mapped site and configured data source, and Watershed counts only months inside the measurement period. To change what is sent, update the site mapping or data sources in integration settings. File downloads still let you choose a date range, sites, and data sources.
What datasets does Nectar send to Watershed?
What datasets does Nectar send to Watershed?
Nectar sends utility usage data for electricity, gas, and water (when enabled) to Watershed. Water uploads include potable and reclaimed supply only.
What happens if my OAuth token expires mid-sync?
What happens if my OAuth token expires mid-sync?
Nectar automatically obtains a new access token before making API requests. If a token expires during a long-running sync, Nectar detects the 401 response and retries with a fresh token.
Which authentication method should I use?
Which authentication method should I use?
OAuth 2.0 is recommended for all new API setups. It provides short-lived tokens, reducing the impact of credential compromise. Bearer tokens are supported for backward compatibility but may be deprecated by Watershed in the future. Choose File download if you prefer to upload XLSX files in Watershed manually.
How do I rotate my Watershed credentials?
How do I rotate my Watershed credentials?
For OAuth: generate new credentials in the Watershed portal and update them in Nectar. For Bearer tokens: generate a new key in Watershed, update it in Nectar, then deactivate the old key. See Watershed’s key rotation guide.