Authentication

All requests to the Leadfeeder API must be authenticated. There are two ways to do it, and both give you access to the same API.

API keys are tied to a single user and do not expire. They are the fastest way to get started.

OAuth 2.0 is tied to an application. Users sign in with their own Leadfeeder account and approve the access the application asks for, and the application receives a short-lived token limited to the scopes it was granted.

Choosing an authentication method

Use an API key for a script you run yourself, a one-off data pull, or an internal tool with a single operator.

Use OAuth 2.0 when the integration is used by more than one person, when it connects Leadfeeder to another system such as a CRM, when you need to limit exactly what it can read and write, or when long-lived credentials are not acceptable in your production environment.

Existing API key integrations keep working unchanged. You can run both side by side.

Not sure which you need? See What is OAuth for the Leadfeeder API? in the Help Center.

Getting your API key

To generate an API key:

Navigate to Settings ⚙ → Personal → API Keys

Create a new API key

Note: If you do not see the API keys section, your user may not have the required permissions.
Please contact your account administrator to grant access.

API Key Authentication

Each Leadfeeder user can generate their own API keys.

A valid API key must be included in every request using the X-Api-Key header.

Example

Accounts and Permissions

With a valid API key, you can access all Leadfeeder accounts your user has permissions for.

Most endpoints require an account_id parameter to specify which account’s data should be retrieved.

To find available accounts, call the /accounts endpoint and use the id from the desired account.

Example

If you only need the ID of one account, you can copy it directly from
Settings ⚙ → Account in the app. See Getting Started for the steps.

Error Handling

If the API key is missing or invalid, the API will return a 403 Forbidden error.

Missing API Key

{
  "code": "missing_token",
  "message": "You need to pass a header named `X-Api-Key` that contains a valid API key."
}

Invalid API Key

{
  "code": "invalid_api_key",
  "message": "The provided API key is invalid. Please generate a new API key."
}

Missing or expired access token

Returned when the access token does not carry the scope the endpoint requires.

{
    "code": "invalid_token",
    "message": "The access token is missing, expired, or invalid. Request a new token."
}

Missing scope

{
    "code": "insufficient_scope",
    "message": "The access token does not include the scope required for this endpoint."
}

Missing scope

Returned when the scope is present but the signed-in user does not have the matching permission in Leadfeeder.

{
    "code": "forbidden",
    "message": "The authenticated user does not have permission to perform this action."
}

OAuth 2.0 authentication

OAuth lets an application call the API on behalf of a Leadfeeder user, with access limited to the scopes that user approved.

Register an application

Before you can use OAuth, someone with the Applications Management permission needs to register an application in Settings > Company > Developer Access > Applications. Registering it produces a Client ID and a Client Secret. See How to create and manage an OAuth application for the full walkthrough.

Endpoints

Setting	Value
Authorization URL	https://api.leadfeeder.com/v1/oauth/authorize
Access Token URL	https://api.leadfeeder.com/v1/oauth/token
Refresh Token URL	https://api.leadfeeder.com/v1/oauth/token
Grant type	Authorization Code with PKCE
Code challenge method	SHA-256
Client authentication	Send client credentials in the request body
Scope format	Space separated list
The Client Credentials grant is not supported. The Leadfeeder API operates at the level of an individual user, so every request is made on behalf of a signed-in person.

Using the access token

Send the token as a bearer token on every request. As with API keys, most endpoints also need account_id.

GET /v1/companies/{id}?account_id=12345 HTTP/1.1
Host: api.leadfeeder.com
Authorization: Bearer YOUR_ACCESS_TOKEN

Scopes

Every endpoint in this reference states the scope it requires. See OAuth applications and scopes for the full list and how scopes combine with platform permissions.

Choosing an authentication method#

Getting your API key#

API Key Authentication#

Accounts and Permissions#

Error Handling#

Missing API Key#

Invalid API Key#

Missing or expired access token#

Missing scope#

Missing scope#

OAuth 2.0 authentication#

Register an application#

Endpoints#

Using the access token#

Scopes#

Choosing an authentication method

Getting your API key

API Key Authentication

Accounts and Permissions

Error Handling

Missing API Key

Invalid API Key

Missing or expired access token

Missing scope

Missing scope

OAuth 2.0 authentication

Register an application

Endpoints

Using the access token

Scopes