Get started

Authentication

Send your key as a Bearer token on every request. Every account check still applies to it.

Every request to the HTTP API carries an API key in the Authorization header:

curl "https://api.leadity.io/v1/account" \
  -H "Authorization: Bearer $LEADITY_API_KEY"

A key is created by a person on the Connectors page of the Leadity app. There is no endpoint that makes one, so a leaked key can never mint another. API keys and scopes covers the kinds of key and what each scope allows.

Treat a key like a password. Keep it in an environment variable or a secret store, never in code you commit or in a browser. A key that leaks should be revoked on the Connectors page at once.

Check the key first

get_account answers the account the key belongs to, its credit balance, any credits expiring within seven days, whether it may still order only the starter packages, and the scopes the key carries. It is the cheapest way to confirm a key works and to learn whether it may spend.

{
  "id": "k7Qm2xRp9T",
  "email": "ops@acme-roofing.com",
  "emailVerified": true,
  "createdAt": "2026-08-14T09:21:44.000Z",
  "credits": 4820,
  "paywalled": false,
  "expiringSoon": null,
  "key": { "kind": "api", "displayPrefix": "lk_api_7fQ2", "scopes": ["read", "write", "spend"] }
}

The account checks every key passes

A key acts as its account, so the account's own state applies to every call it makes. These refusals are about the account, not the key:

Code	Status	What to do
`account_suspended`	403	The account is suspended. Contact Leadity support.
`email_not_verified`	403	Verify the account's email address in the app.
`paywall_required`	402	The operation needs a purchase on the account first: the upgrades to a finished scrape and `create_validation` refuse until the account has bought credits.

When the key itself is refused

Code	Status	Meaning
`unauthorized`	401	The key is missing, malformed, revoked or expired.
`wrong_key_kind`	401	An MCP key was sent to the HTTP API, or an API key to the MCP server.
`insufficient_scope`	403	The key lacks the scope this operation needs. The body names it as `requiredScope`.

A key's scopes are fixed when it is created. To give an integration more, create a new key with the scopes it needs and revoke the old one.