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.

PrefixMode
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

PermissionCan
readRead leads, contacts, messages, profiles, events.
writeAlso send messages, record outcomes, edit profiles, sources, webhooks and contacts.
adminAlso 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.

Was this page helpful?