API Authentication

Q: What HTTP header authenticates Lead Distro AI API requests?

`x-api-key`. Pass the supplier's API key as the value. The header is required on every POST to the ingest endpoint and every POST to the ping endpoint. Missing or invalid keys return 401; valid keys for the wrong campaign return 403.

Q: Can I use Bearer token authentication instead of x-api-key?

No — Lead Distro AI only accepts `x-api-key`. Bearer tokens (`Authorization: Bearer ...`) are not recognized and return 401. The simpler API-key model fits the supplier integration pattern; OAuth-style flows would add complexity without security benefit at this layer.

Q: What's the difference between 401 and 403 on the ingest endpoint?

401 Unauthorized means the API key is missing, invalid, or expired (e.g., the supplier was deleted). 403 Forbidden means the key is valid but the supplier isn't attached to the campaign specified in `flo_campaign_id`. 401 = fix the key; 403 = attach the supplier to the campaign or fix the campaign ID.

Authenticate Lead Distro AI API requests: the source x-api-key header for lead ingest and the organization API key (Bearer) for the Actions API. Key types, header format, error codes (401/403), and FAQs.

Last updated: September 9, 2026

Authentication Model

Lead Distro AI's ingest API uses a per-supplier API key authentication model. Every request includes the key in the x-api-key HTTP header. The key identifies the supplier; the request body's flo_campaign_id specifies which campaign to route the lead into. The supplier must be attached to that campaign or the request returns 403.

Header Format

x-api-key: <your-supplier-api-key>

The header name is case-insensitive per HTTP spec. The key value is treated as opaque — don't parse it; treat it as a single secret string.

Two kinds of key

Key	Header	Who holds it	What it does
Source key	`x-api-key:`	A lead source (vendor, form, your own site)	Sends leads into one campaign and reads back its own leads. Found on the source detail page.
Organization API key	`Authorization: Bearer ldk_live_...`	Your team (admins create it in Settings, MCP & API)	Manages the account: campaigns, destinations, sources, leads, funnels, reports, Partner Portal. Powers the Actions API and the MCP. Permissions are set per area, read or write.

A new organization API key is read only until you turn on Write for an area. Billing actions are never available to any key.

Error Codes

Status	Reason	Fix
401 Unauthorized	Header missing or key invalid	Check the header name (`x-api-key`), confirm the key matches what's on the supplier detail page
403 Forbidden	Key valid but supplier not attached to the specified campaign	Attach the supplier to the campaign in the dashboard, or fix the `flo_campaign_id` in the request body
429 Too Many Requests	Rate limit exceeded	Back off — see Rate Limits for the response headers indicating retry-after

Authentication for Different Endpoints

Endpoint	Auth required	Header
POST /api/v1/ingest	Yes	`x-api-key`
POST /api/v1/ping (V2)	Yes	`x-api-key`
GET /api/v1/leads/lookup	Yes	`x-api-key` (read-only scope)

Server-to-server only. Never embed x-api-key in client-side JavaScript, mobile apps, or any code reachable from a browser — keys exposed to clients can be extracted within minutes by attackers and used to flood your campaign with junk leads.

Frequently Asked Questions

What HTTP header authenticates Lead Distro AI API requests?

x-api-key. Pass the supplier's API key as the value. The header is required on every POST to the ingest endpoint and every POST to the ping endpoint. Missing or invalid keys return 401; valid keys for the wrong campaign return 403.

Can I use Bearer token authentication instead of x-api-key?

No — Lead Distro AI only accepts x-api-key. Bearer tokens (Authorization: Bearer ...) are not recognized and return 401. The simpler API-key model fits the supplier integration pattern; OAuth-style flows would add complexity without security benefit at this layer.

What's the difference between 401 and 403 on the ingest endpoint?

401 Unauthorized means the API key is missing, invalid, or expired (e.g., the supplier was deleted). 403 Forbidden means the key is valid but the supplier isn't attached to the campaign specified in flo_campaign_id. 401 = fix the key; 403 = attach the supplier to the campaign or fix the campaign ID.

Can I rotate an API key without breaking the integration?

Lead Distro AI doesn't support in-place key rotation today. The clean path is delete-and-recreate the supplier: the old key dies, a new key is generated, the supplier updates their integration. There's a brief downtime window during the swap — schedule it during a low-traffic period and coordinate with the supplier.

How do I rate-limit suppliers that misbehave?

Lead Distro AI applies a global rate limit (100 RPS per supplier key, burst 200 RPS for 10 seconds) automatically. For tighter per-supplier limits, set ping caps and lead caps on the supplier — caps trigger a pause when hit, which is a more graceful degradation than rate-limiting. For abusive suppliers, delete-and-recreate to invalidate their key.

Are API requests authenticated over TLS?

Yes — Lead Distro AI's API endpoints are HTTPS-only. HTTP requests are rejected by the edge before reaching the API layer. Confirm your supplier integrations use https:// URLs, never http://. TLS 1.2 minimum.

Lead Ingest API

Complete Lead Distro AI API reference: the Actions API for managing your account with an organization API key (with an OpenAPI file), plus the lead ingest endpoint with field validation, signed webhooks, authentication, and rate limits.

Supplier API Key Setup

Generate, rotate, and secure Lead Distro AI supplier API keys. Authentication header format, key compromise recovery, IP allowlisting, and FAQs.

API Response Codes & Rate Limits

Complete list of Lead Distro AI API HTTP status codes, error response shapes, and rate limits for ingest and ping endpoints.

If you have any questions, send us an email at support@leaddistro.ai

Supplier Portal API Response Codes & Rate Limits