OAuth endpoints, scopes and the authorization flow

This article is the reference for developers building against the Leadfeeder API with OAuth. If you have not registered an application yet, start with How to create and manage an OAuth application.

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
Token header prefix	`Bearer`
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.

The flow

Your application redirects the user to the Authorization URL, with your Client ID, one of your registered redirect URLs, the scopes you need, a state value, and a PKCE code challenge.
The user signs in to Leadfeeder. Sign-up is not offered in this flow, so the user needs an existing account.

If you are building against the API and do not have an account yet, you can try Leadfeeder for free. It is a 14-day free trial and no credit card is required.
The user sees the authorization screen with your application name, logo, description, and the scopes you asked for. They approve or deny.
On approval, Leadfeeder redirects back to your redirect URL with an authorization code.
Your application exchanges that code at the Access Token URL for an access token and a refresh token.
You call the API with the access token in the Authorization header, prefixed with Bearer.
When the access token expires, you exchange the refresh token at the same token endpoint for a new one. The user does not sign in again.

Using the access token

Send the token as a bearer token on every request.

Authorization: Bearer [YOUR_ACCESS_TOKEN]

As with API keys, most endpoints also need your account_id as a query parameter.

<https://api.leadfeeder.com/v1/companies/{id}?account_id=[YOUR_ACCOUNT_ID]>

Available scopes

Scopes control which resources your application can reach. Each is split into read and write where it applies. In the platform you search for scopes by their friendly name, and the technical value is shown underneath.

Every endpoint in the API reference states the scope it needs. The machine-readable list lives in the OpenAPI spec at https://api.leadfeeder.com/openapi.yaml, under components.securitySchemes.OAuth2.

Read scopes

Scope	Name in the UI	What it covers
`accounts:read`	View account details	Account information and the remaining credit balance.
`buyer_personas:read`	View buyer personas	The account's buyer personas.
`campaigns:read`	View campaigns	Campaigns and their performance statistics.
`companies:read`	View companies	Company data, profiles, firmographics, and web visit matches.
`contacts:read`	View contacts	Contact data and profiles, including personal details such as names and email addresses.
`crm_records:read`	View CRM matches	CRM connection and matching data linked to companies or contacts.
`custom_fields:read`	View custom fields	Custom field definitions and their values.
`icps:read`	View ideal customer profiles	The account's Ideal Customer Profiles.
`ip:read`	Look up IP data	Resolve and enrich IP addresses to company data.
`lists:read`	View lists	Lists and the companies and contacts in them.
`tags:read`	View tags	See all tags that can be assigned on companies.
`usage:read`	View API usage	API usage statistics for the account.
`web_visits:read`	View website visits	See website visitor activity, tracker data, and custom feeds.

Write scopes

Scope	Name in the UI	What it covers
`campaigns:write`	Manage campaigns	Update existing campaigns.
`companies:write`	Manage company lists and tags	Add companies to lists, apply tags, and run enrichment jobs. Cannot create or delete companies.
`contacts:write`	Manage contact list assignments	Add or remove contacts from lists and run contact-data enrichment. Cannot create or delete contacts.
`custom_fields:write`	Manage custom fields	Create, update, and delete custom field definitions.
`lists:write`	Manage lists	Create, rename, and delete lists.
`tags:write`	Manage tags	Create, update, and delete tags.
`web_visits:write`	Manage custom feeds	Create, update, and delete custom feeds. Does not change visit data itself.

Common errors

Error	What it means	How to fix it
`insufficient_scope`	The access token does not carry the scope this endpoint needs.	Add the scope to the application, then have the user authorize again.
`forbidden`	The scope is there, but the signed-in user does not have the matching permission in Leadfeeder.	Check that user's permissions in the platform.
`401 Unauthorized`	The access token is missing, malformed, or expired.	Check the `Bearer` prefix, and refresh the token if it has expired.

If a scope was removed from the application, calls against it start failing straight away. If a scope was added, it will not work until the user authorizes the application again.

--

Questions, comments, feedback? Please let us know by contacting our support team via the chat or by sending us an email at support@leadfeeder