---
title: "Partners & connect links"
url: https://docs.light-ai.app/partners.md
canonical_url: https://docs.light-ai.app/partners
last_updated: 2026-10-13
summary: "Agencies and integrators serve many contractors from one partner account: one key, one webhook endpoint, a consented grant per contractor."
api_status: beta
related:
  - https://docs.light-ai.app/partners/onboarding
  - https://docs.light-ai.app/partners/connect
  - https://docs.light-ai.app/api-reference/partners
---

# Partners & connect links

> Agencies and integrators serve many contractors from one partner account: one key, one webhook endpoint, a consented grant per contractor.

A partner account connects to each contractor through a **grant**: the contractor's owner approves your access once, with exactly the scopes you ask for. You never handle their passwords or API keys.

## Developer accounts

- **By private invite.** Strategic partners get a free developer account from Light AI. It has the developer console (partner keys, connect links, partner webhooks, connected contractors), the docs and settings only: no projects, no credits, no plan or billing. E-mail [support@light-ai.app](mailto:support@light-ai.app) to ask for an invite.
- The invite is a single-use link valid for 7, 14 or 30 days. Sign up with a new work e-mail (an existing Light AI account is never converted); when Light AI pinned your company domain, the address must be at that domain.
- Teammates join as admins (up to 10 members). A developer account reaches a contractor's data only after that contractor, on Pro, approves your connect link.
- Existing Pro organizations can also apply for partner status in Settings → Developers.
- Your verified legal name and domain are shown to every contractor on the consent screen.

## Contractors must be on Pro

A grant carries data only while the contractor is on Pro (Pro, Enterprise or a Pro trial). Free and Plus organizations cannot approve a connect link. If a contractor drops below Pro, their grant stops carrying data (you receive `organization.entitlement_changed`) and resumes when they upgrade.

## How it works

1. Create a [connect link](https://docs.light-ai.app/partners/connect) with the scopes you need and your own `external_reference` for the contractor.
2. The contractor's owner opens it, signs in (or signs up), reviews your name, domain and scopes, and approves.
3. You receive `grant.created` and the browser returns to your `redirect_uri`.
4. Act for that contractor by adding `Light-AI-Organization: org_…` to your requests.

curl:

```bash
curl "https://api.light-ai.app/v1/leads?limit=10" \
  -H "Authorization: Bearer $LIGHT_AI_API_KEY" \
  -H "Light-AI-Organization: $LIGHT_AI_ORGANIZATION"
```

JavaScript:

```javascript
const response = await fetch('https://api.light-ai.app/v1/leads?limit=10', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,
    'Light-AI-Organization': process.env.LIGHT_AI_ORGANIZATION,
  },
});
const data = await response.json();
```

Python:

```python
import os, requests

response = requests.get(
    "https://api.light-ai.app/v1/leads?limit=10",
    headers={
        "Authorization": f"Bearer {os.environ['LIGHT_AI_API_KEY']}",
        "Light-AI-Organization": os.environ["LIGHT_AI_ORGANIZATION"],
    },
)
data = response.json()
```

## Partner keys

- Created in the partner console with a second factor. They expire after 30, 60 or 90 days; up to 5 can be active per mode, so you can rotate without downtime.
- Effective scopes are key ∩ grant ∩ the contractor's plan. `GET /v1/me` with `Light-AI-Organization` shows them for one contractor.
- 600 requests a minute per partner key, plus each contractor's own limits. See [Rate limits](https://docs.light-ai.app/rate-limits).

## Webhooks for many contractors

A **partner-wide endpoint** receives events from every connected contractor, each with `grant.external_reference` for routing, and fair per-contractor lanes so one busy contractor never delays the others. The partner owner creates it in the console with a second factor (never with a key). A partner key can also create an endpoint for one contractor (`Light-AI-Organization` + `webhooks:manage`).

Polling instead: `GET /v1/events?sort=sync_asc` with a partner key and no organization header lists events from every connected contractor under one cursor.

## Revocation

A contractor can disconnect at any time in Settings → Developers → Connected partners. You receive `grant.revoked` (a final, minimal event) and further calls for that organization fail. Quote links you already handed to homeowners keep working.