Partners & connect links

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 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 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 "https://api.light-ai.app/v1/leads?limit=10" \
  -H "Authorization: Bearer $LIGHT_AI_API_KEY" \
  -H "Light-AI-Organization: $LIGHT_AI_ORGANIZATION"

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();

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.

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.