Authentication
Every request is authenticated with a bearer token in the Authorization header. Programs use API keys; a user session is only needed to sign in and create the first key.
curl https://core.leadveyor.com/v1/leads \
-H "Authorization: Bearer lv_live_…"
API keys
Create keys with POST /v1/api-keys. The secret is returned once; Leadveyor stores only its hash. Revoke a key at any time with POST /v1/api-keys/{id}/revoke.
| Prefix | Mode |
|---|---|
lv_live_… | Live data. |
lv_test_… | Test data: everything created with a test key is kept apart from live data (livemode: false) and never mixed with it. |
Permissions
| Permission | Can |
|---|---|
read | Read leads, contacts, messages, profiles, events. |
write | Also send messages, record outcomes, edit profiles, sources, webhooks and contacts. |
admin | Also manage API keys and workspaces. |
A key can't have more permissions than whoever created it.
Workspace and account-wide keys
A key created with a workspaceId works only in that workspace — no extra header is needed. An account-wide key (no workspaceId) can reach every workspace of the account and must say which one in every request:
curl https://core.leadveyor.com/v1/leads \
-H "Authorization: Bearer lv_live_…" \
-H "Leadveyor-Workspace: ws_1Bq7Xn4KpRz9Lc2Vt6Hy0Mde"
Use workspace keys for integrations (a CRM, n8n, an agent) and account-wide keys for tools that manage several businesses, such as an agency's dashboard.
The same keys authenticate the MCP server (https://core.leadveyor.com/mcp): an AI assistant connected with a key can do exactly what the key allows through the API.
Sessions
POST /v1/auth/signup and POST /v1/auth/login return a session token (lvs_…, valid 30 days). Sessions have the user's role in the account and are meant for the console and for creating the first API key. A user who belongs to several accounts picks one with the Leadveyor-Account header.
Never put API keys in browser or mobile code. To receive web forms, use a form source — its URL is public by design and needs no key.