API Authentication

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 with the supplier x-api-key header. Key generation, rotation, header format, error codes (401/403), and FAQs.

Last updated: May 22, 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.

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](/docs/api-response-codes) 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. Ingest leads via REST endpoints with field validation, signed webhooks, authentication, rate limits, and full example requests for every lead distribution endpoint.

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, rate limits, and exponential backoff recipe 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