Authentication & Security

API key + IP allowlist + idempotency. Defense in depth.

API Key

• Header: x-api-key
• Format: lmn_prd_<28 url-safe base64 chars> (production) or lmn_stg_<28 url-safe base64 chars> (sandbox).
• Transport: keys are shared via one-time secret link at onboarding. Never commit to source; never transmit in URLs.
• Rotation: coordinated out-of-band; both old and new keys are accepted during a brief overlap window for zero-downtime cutover.
• Errors:
  • 401 missing_api_key — x-api-key header absent.
  • 401 invalid_api_key — key not recognized, revoked, or wrong environment (e.g., lmn_stg_* against api.lmnauto.com).

X-User-Id (optional, attribution)

Send an X-User-Id header on any request to attribute it to the individual end-user/dealer within your org. Useful for per-dealer analytics and curation.

GET /v1/vehicles HTTP/1.1
x-api-key: lmn_prd_...
X-User-Id: your-internal-user-id

• Optional — omitting it is never an error.
• Not authenticated — LMN does not validate, resolve, or reject the value. Authentication is solely on x-api-key. This is opaque attribution metadata only.
• Format — any stable opaque string; your namespace to define. Send the same value for the same user so attribution groups correctly (grouping is by exact, case-sensitive value). X_User_Id is accepted as an alternate header name.
• Privacy — LMN’s request logs store a one-way SHA-256 hash of the value, not the raw string.
• Where used — LMN’s logging/audit pipeline only; not stored on order resources.

IP Allowlist

Requests are accepted only from pre-registered partner egress IPs.

• Up to 16 addresses or CIDR ranges per environment — IPv4 and IPv6 both supported (e.g., 203.0.113.0/24, 2001:db8::/32).
• Sandbox and production have independent allowlists.
• Requests from unlisted IPs return 403 ip_not_allowed.
• Matching is per-family: if your client egresses over both IPv4 and IPv6 (dual-stack), register ranges for both families — otherwise requests intermittently fail when the unlisted family is used.

To add or change IPs, email [e-mail] with at least 72 hours notice. Emergency same-day changes via [e-mail].

TLS Requirements

• Minimum TLS 1.2 (TLS 1.3 preferred).
• Forward-secret cipher suites required (ECDHE-*).
• Public CA chain — no certificate pinning required.

Idempotency-Key (required on order creation)

POST /v1/orders must include an Idempotency-Key header with a UUID v4 value.

Idempotency-Key: 8e8b2a70-7a4f-4f7c-9e3a-8ed4f8c3a9d1

• LMN enforces a permanent unique constraint on (api_key, idempotency_key). Replays return the cached response (same status, same body). Safe to retry on timeouts.
• Missing on POST /v1/orders returns 400 missing_idempotency_key.
• Reusing an Idempotency-Key with a different vehicle_id returns 422 idempotency_key_reused — generate a fresh key per logical request, never reuse across different orders.

Safe vs unsafe key reuse

Scenario	Result	Example
Same key + same body (network retry)	✅ Safe — returns the original response, no duplicate created	Same vehicle_id, same max_bid_amount_usd
Same key + different body	❌ 422 idempotency_key_reused with details.original_vehicle_id	Different vehicle_id than the original POST
Different key + same body	⚠️ Treated as a new request — 409 duplicate_order if active order already exists for that vehicle	Generated a fresh key for what should have been a retry

Rule of thumb: generate the Idempotency-Key once at the moment of order intent, then reuse it across all retries of the same logical request. Never reuse across different logical requests.

Rate Limits

Per-API-key sliding-window buckets:

Bucket	Endpoints	Limit
Read-heavy	GET /v1/vehicles, GET /v1/vehicles/facets	600 req/min
Read-light	GET /v1/orders/{id}, GET /v1/orders	300 req/min
Write	All POST, DELETE	60 req/min

When exceeded, response is 429 rate_limited with Retry-After header (seconds until window resets). Apply client-side exponential backoff.

Webhook signing

All webhooks LMN sends to your endpoint are signed with HMAC-SHA256 (Stripe-compatible scheme). See Webhooks → Signing for verification details.