Leadron API Documentation

Authentication

External integrations authenticate using API keys sent via the X-API-Key header. All requests must go through the API Gateway — direct calls to backend services are not permitted.

API Keys

Server-to-server with tenant-scoped keys

Impersonation

Act on behalf of any tenant user

Usage Tracking

Monthly API call limits per plan tier

API Key Authentication

Key Format

API keys follow a predictable prefix format that indicates the environment. The full key is shown only once at generation time — store it securely.

Key format

bash

# Live key (production data)
ldr_live_sk_a1b2c3d4e5f6g7h8i9j0

# Sandbox key (test data)
ldr_sandbox_sk_a1b2c3d4e5f6g7h8i9j0

Key Segments

Parameter	Type	Default	Description
`ldr`req	`prefix`	—	Leadron platform identifier
`live \| sandbox`req	`environment`	—	Determines which dataset the key operates on
`sk`req	`type`	—	Secret key identifier
`<random>`req	`string`	—	Cryptographically random suffix

Environments

Environment	Prefix	Purpose
Live	ldr_live_sk_	Production data — real operations, counts toward usage limits
Sandbox	ldr_sandbox_sk_	Test environment — safe for development and integration testing

Sending Requests

Include your API key in the X-API-Key header on every request. The tenant is automatically resolved from the key — no X-Tenant-Id header is required.

$ curl https://api.leadron.io/v1/leads \
  -H "X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json"

No Bearer token needed

When using an API key, do not include an Authorization header. The X-API-Key header is the only authentication mechanism for external integrations.

Acting on Behalf of Users

By default, API key requests are attributed to the user who created the key. To perform actions as another user in the same tenant (e.g. assigning leads on their behalf), use the X-On-Behalf-Of header.

How It Works

Create lead as another user

http

POST /v1/leads
X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0
X-On-Behalf-Of: 2fGh8kLmNpQrStUv
Content-Type: application/json

{
  "email": "jane@acme.com",
  "firstName": "Jane",
  "lastName": "Doe"
}

How identities are tracked

ActorThe user specified in X-On-Behalf-Of — this user is recorded as the creator/assignee in the downstream service.

Key OwnerThe user who generated the API key — always recorded in the audit log for accountability.

Restrictions

The target user must belong to the same tenant as the API key.

The target user must have an active account.

If the target user ID is invalid or not found, the request returns 403 Forbidden.

Both the key owner and the acting user are recorded in audit logs.

Response403Forbidden

Returned when the X-On-Behalf-Of user is invalid or not in the same tenant.

403 Response

json

{
  "success": false,
  "status": 403,
  "message": "Target user not found or not in the same tenant",
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

API Key Management

Create, list, and revoke API keys programmatically. Keys can also be managed from the Settings → Integrations page in the dashboard.

Creates a new API key for the authenticated tenant. The full key is returned only in this response — store it immediately and securely.

Body Parameters

Parameter	Type	Default	Description
`name`req	`string`	—	Human-readable name for this API key (max 100 chars)
`environment`	`string` livesandbox	live	Key environment

Request

HTTP

http

POST https://api.leadron.io/v1/api-keys
X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0
Content-Type: application/json

Body

json

{
  "name": "Zapier Integration",
  "environment": "live"
}

Response201Created

201 Response

json

{
  "success": true,
  "status": 201,
  "message": "API key generated",
  "data": {
    "id": "3xYz9aBcDeFgHiJk",
    "name": "Zapier Integration",
    "keyPrefix": "ldr_live_sk_",
    "environment": "live",
    "status": "active",
    "fullKey": "ldr_live_sk_q8w7e6r5t4y3u2i1o0p9",
    "createdAt": "2026-02-08T14:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

Store the key immediately

The fullKey field is only returned at creation time. It cannot be retrieved later — if lost, revoke the key and generate a new one.

Usage & Limits

API call usage is tracked per tenant on a monthly billing cycle. Each plan tier has a maximum number of API calls per month. When the limit is reached, requests return 429 Too Many Requests.

Usage Tracking

Plan	Monthly API Calls	Rate Limit
Free	1,000	60 req/min
Starter	10,000	300 req/min
Pro	100,000	1,000 req/min
Team	500,000	5,000 req/min
Enterprise	Custom	Custom

Rate Limit Headers

Every response from an API key request includes usage headers:

Response Headers

Parameter	Type	Default	Description
`X-RateLimit-Limit`	`integer`	—	Requests allowed per minute
`X-RateLimit-Remaining`	`integer`	—	Requests remaining in this window
`X-RateLimit-Reset`	`integer`	—	Unix timestamp when the window resets
`X-API-Usage-Current`	`integer`	—	Total API calls used this billing month
`X-API-Usage-Limit`	`integer`	—	Monthly API call limit for this plan

Response429Too Many Requests

Returned when the monthly API call limit or per-minute rate limit is exceeded.

429 Response

json

{
  "success": false,
  "status": 429,
  "message": "API call limit exceeded. Upgrade your plan for higher limits.",
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

Encoded IDs

All resource IDs in API responses are encoded as alphanumeric strings (16-17 characters) for security. Use these IDs as-is in path parameters, query parameters, request bodies, and the X-On-Behalf-Of header.

IDs in responses are encoded

json

{
  "data": {
    "id": "2fGh8kLmNpQrStUv",
    "assignedTo": "3xYz9aBcDeFgHiJk",
    "email": "jane@acme.com"
  }
}

Tip

The encoding is handled entirely by the API Gateway. You never need to encode or decode IDs yourself.

Error Responses

Authentication-related error responses you may encounter when using API keys:

Response401Unauthorized

The API key is missing, invalid, expired, or revoked.

401 Response

json

{
  "success": false,
  "status": 401,
  "message": "Invalid or missing API key",
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

Response403Forbidden

The API key is valid but lacks permission for this operation, or the X-On-Behalf-Of user is not in the same tenant.

403 Response

json

{
  "success": false,
  "status": 403,
  "message": "Insufficient permissions",
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

Response429Too Many Requests

Monthly API call limit or per-minute rate limit exceeded.

429 Response

json

{
  "success": false,
  "status": 429,
  "message": "API call limit exceeded. Upgrade your plan for higher limits.",
  "meta": {
    "timestamp": "2026-02-08T14:30:00.000Z",
    "version": "v1"
  }
}

Security Best Practices

Never expose keys in client code

API keys are server-side secrets. Never include them in frontend JavaScript, mobile apps, or public repositories.

Use environment variables

Store API keys in environment variables or a secrets manager. Never hard-code keys in source code.

Rotate keys regularly

Generate new keys periodically. Revoke old keys immediately after rotating to a new one.

Use sandbox for testing

Use sandbox keys during development and CI/CD. Reserve live keys for production systems.

One key per integration

Create separate API keys for each external integration. This makes it easy to revoke access for a single service.

Monitor usage

Check the X-API-Usage-Current header or the dashboard to monitor consumption and detect anomalies.

If a key is compromised

Immediately revoke the key from the dashboard or via DELETE /v1/api-keys/:id. Generate a new key and update your integration. Review audit logs for any unauthorized activity.