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

# Developer guide

> Technical onboarding for Nectar API integrations and embedded workflows.

This section is for engineers integrating Nectar into applications, pipelines, and internal tooling.

## Start here

Use this order for the fastest implementation path:

1. [Get your API key](/developer-guide/getting-started#api-key-setup-in-settings)
2. [Make your first API request](/developer-guide/getting-started#make-your-first-request)
3. [Run sandbox testing](/developer-guide/sandbox-testing)
4. [Implement webhooks](/developer-guide/webhooks)
5. [Add connection invitations (optional)](/developer-guide/connection-invitations)
6. Use [API Reference](/api-reference) for endpoint details

## API key setup in Settings

Create keys in **Settings > Organization > API Keys**.

### Recommended key setup

| Environment | Recommendation                          | Why                                                    |
| ----------- | --------------------------------------- | ------------------------------------------------------ |
| Sandbox     | Create one key per test app/integration | Isolate test traffic and avoid shared-secret confusion |
| Production  | Create separate keys per service        | Safer rotation and scoped blast radius                 |

### Rotation without downtime

<Steps>
  <Step title="Create a replacement key">
    Generate a new key before touching the current one.
  </Step>

  <Step title="Deploy the new key">
    Update your service configuration or secret manager and deploy.
  </Step>

  <Step title="Verify traffic">
    Confirm successful requests and webhook processing with the new key.
  </Step>

  <Step title="Delete old key">
    Revoke the old key only after the new key is live everywhere.
  </Step>
</Steps>

## Choose your API version

| Version | Status         | Guidance                                                |
| ------- | -------------- | ------------------------------------------------------- |
| v2.2    | Recommended    | Use this for all new integrations                       |
| v2.1    | Supported      | Maintain existing integrations, plan migration          |
| v2.0    | Legacy support | Use only for older integrations that cannot migrate yet |

For all new integrations, start on **v2.2**.

## Common implementation tracks

<CardGroup cols={2}>
  <Card title="API getting started" icon="rocket" href="/developer-guide/getting-started">
    Authentication, first request, and data model basics.
  </Card>

  <Card title="Sandbox testing" icon="flask" href="/developer-guide/sandbox-testing">
    Validate behavior with non-production data and workflows.
  </Card>

  <Card title="Webhooks" icon="bell" href="/developer-guide/webhooks">
    Build event-driven synchronization with signature verification.
  </Card>

  <Card title="Connection invitations" icon="paper-plane" href="/developer-guide/connection-invitations">
    Embed Nectar connection flows in your product experience.
  </Card>
</CardGroup>

## Related pages

* [Data model overview](/developer-guide/data-model/overview) — understand the relationships between companies, sites, accounts, meters, and bills
* [Connection statuses](/developer-guide/connection-statuses) — handle connection lifecycle events in your integration
* [Methodology](/platform/methodology/overview) — how Nectar processes, calendarizes, and attributes bill data
* [Getting started (platform)](/platform/getting-started) — platform walkthrough for non-developer users on your team

## Developer FAQ

<AccordionGroup>
  <Accordion title="My API call returns 401. What should I check first?">
    Confirm the `X-API-Key` header is present, your key is active, and you are using the correct
    environment key (sandbox vs production).
  </Accordion>

  <Accordion title="How do I test that a key is valid quickly?">
    Call `/ping` on your target API version. A `200` response confirms the key is accepted.
  </Accordion>

  <Accordion title="What causes 403 or 404 when authentication is valid?">
    Usually scope, object visibility, or incorrect resource identifiers. Verify the company context
    and object IDs your integration is requesting.
  </Accordion>

  <Accordion title="What should I do for webhook retries and idempotency?">
    Treat webhook deliveries as at-least-once and build idempotent handlers keyed by event ID. Retry
    transient failures and log processed IDs.
  </Accordion>

  <Accordion title="How should I handle expired invitations?">
    Detect expiry in your UI flow and request a freshly created invitation from your backend before
    retrying the embedded session.
  </Accordion>
</AccordionGroup>