> ## 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.

# Watershed

> Watershed integration for carbon accounting and climate program management.

<Tip>
  Need help in this area? See [Data Export FAQ](/platform/data-export/faq).
</Tip>

The Watershed integration connects Nectar to Watershed's enterprise climate platform. Nectar pushes utility data directly via the Watershed API — no manual file import required.

## Authentication

Nectar supports two authentication methods for connecting to the Watershed API:

### OAuth 2.0 Client Credentials (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:**

1. Log in to the [Watershed portal](https://app.watershedclimate.com) and navigate to the **API** section under **Organization settings**.
2. Click **Create credentials** to generate a new Client ID and Client Secret.
3. Give the client a name, assign a role, and set the token expiration time (in minutes).
4. Save the Client Secret securely — Watershed will not display it again.
5. In Nectar, go to [**Data Export > Integrations > Watershed**](https://dash.nectarclimate.com/data-export/integrations/watershed) and choose **OAuth Client Credentials** as the authentication mode.
6. Enter the Client ID and Client Secret. Nectar handles token exchange and renewal automatically.

Nectar exchanges credentials for an access token by calling Watershed's `/oauth/token` endpoint with `grant_type=client_credentials`. Tokens are refreshed automatically before expiration — Watershed does not use refresh tokens.

<Note>
  A common starting point for token lifetime is 60 minutes. Shorter lifetimes offer tighter security but increase token exchange frequency.
</Note>

### 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:**

1. Generate a Bearer Token API key in the Watershed portal under **Organization settings > API**.
2. In Nectar, choose **Bearer Token** as the authentication mode and paste the key.

<Warning>
  Watershed recommends OAuth 2.0 for all new integrations. Bearer tokens may be deprecated in the future. See [Watershed's OAuth guide](https://api-docs.watershed.com/docs/how-to-use-oauth-20-for-api) for migration steps.
</Warning>

### Regional endpoints

Nectar supports both Watershed API regions:

| Region | API host                      |
| ------ | ----------------------------- |
| Global | `api.watershedclimate.com`    |
| EU     | `eu.api.watershedclimate.com` |

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**](https://dash.nectarclimate.com/data-export/integrations/watershed) and complete setup from [**Settings > Company > Integrations > Watershed**](https://dash.nectarclimate.com/settings/company/integrations/watershed) or the setup wizard when prompted. Steps include:

1. **Authentication** — Choose OAuth or Bearer Token and enter credentials.
2. **Connection test** — Nectar validates the credentials by fetching available datasets from Watershed.
3. **Dataset selection** — Choose which upload schemas to use for electricity and gas.
4. **Site mapping** — Map Nectar sites to Watershed building identifiers (include or exclude each site).

Once setup is complete, the integration hub shows **Connected** and API push is available when every site is configured and at least one data source is enabled.

## Integration hub

The Watershed integration page at [**Data Export > Integrations > Watershed**](https://dash.nectarclimate.com/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
* **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. Configure utility type, date range, and sites, and choose whether to push the data to Watershed via API or download an XLSX for manual upload. A progress dialog shows upload status.

The sync process follows Watershed's Data Ingestion API workflow:

1. **Create upload** — Registers a new upload with Watershed, specifying the dataset and schema.
2. **Load data** — Sends usage records in batches (up to 10,000 records per request).
3. **Validate** — Watershed checks the uploaded data against the schema and reports errors.
4. **Submit** — Marks the upload as final and associates it with a measurement task.

<Warning>
  Once data is submitted to Watershed, it cannot be modified via the API. Ensure your data is correct before running the export.
</Warning>

### Recent syncs & downloads

The history card lists your latest Watershed exports and API pushes. Click a **sync** row to open the [upload detail page](#upload-detail-page). Click a **download** row to open the export detail sheet with configuration and a re-download link. Use [**Data Export > History**](https://dash.nectarclimate.com/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. Unlike Metrio and Sphera, Watershed data **cannot be edited once submitted**, so this view is for *finding* discrepancies and deciding what to re-upload — there are no inline Push/Sync buttons.

**How to use it:**

1. **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.
   * **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.
2. **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.
3. **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.

**Statuses:**

* **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

**Resolving discrepancies:** Because Watershed uploads are immutable, correct the data at the source and re-upload:

1. 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.
2. If Nectar is wrong, fix the bills in [Data Inventory](/platform/data-inventory/overview), then run a new export for the affected scope.
3. If Watershed is wrong, delete the affected upload in your Watershed dashboard first, then re-export from Nectar with **Upload to Watershed** enabled.

New uploads appear as additional datasets in the comparison once Watershed validates them.

## 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. Each record includes:

| Field                     | Description                                            |
| ------------------------- | ------------------------------------------------------ |
| `building_identifier`     | Watershed building name (mapped from your Nectar site) |
| `start_date_inclusive`    | First day of the billing month (YYYY-MM-DD)            |
| `electricity_consumption` | Monthly electricity usage value                        |
| `electricity_unit`        | Unit of measurement (kwh or mwh)                       |
| `fuel_type`               | Fuel type (Natural Gas)                                |
| `fuel_consumption`        | Monthly gas usage value                                |
| `fuel_unit`               | Unit of measurement (therm, ccf, mmbtu, etc.)          |

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I edit data after uploading to Watershed?">
    No. Watershed does not allow modification of submitted data via API. If you need to correct data, you may need to work with Watershed support or use their manual correction workflows.
  </Accordion>

  <Accordion title="What datasets does Nectar send to Watershed?">
    Nectar sends utility usage data (electricity and gas) to the Utilities dataset in Watershed. Other datasets may be added as Nectar expands data type support.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Which authentication method should I use?">
    OAuth 2.0 Client Credentials is recommended for all new 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.
  </Accordion>

  <Accordion title="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](https://api-docs.watershed.com/docs/how-to-rotate-api-keys).
  </Accordion>
</AccordionGroup>