A Service User lets an application or AI agent connect to the Leadfeeder API or MCP server without a person signing in. You create it by choosing "Dedicated service user" when you register an OAuth app in Developer Access. The app then acts as its own identity, and it keeps working when employees join or leave.This guide covers the API and the MCP server.When to use a Service User#
When you create an OAuth app, you choose who it "Acts as". | People who connect it | Dedicated service user |
|---|
| Who makes the calls | Each person who connects the app signs in and grants their own access | The app's own service user, named after the app |
| Sign-in needed | Yes | No |
| Redirect URIs | Required | Not used |
| Account access | The accounts of the person who connected | Every account in your company, including accounts created later |
| If a person leaves | Their access stops | Not affected |
| Best for | Apps people connect to with their own login | Shared AI agents, background jobs, automations and partner apps that call the API or MCP server |
This choice is permanent. You select "Acts as" when you create the app, and it cannot be changed afterwards. If you need the other mode, create a new app.
What a Service User is and is not#
• It is created for you when you create the app and removed when you delete the app.
• It has no password and cannot sign in to Leadfeeder.
• It does not appear in team management and does not use a seat.
• Calls are attributed to the app, not to a person.
• Credits are charged normally to the account the call is made on.Before you start#
You need the Applications Management permission. If you do not see Developer Access under Settings > Company, ask a company admin to grant it.Step 1: Create the app#
1.
Go to Settings > Company > Developer Access.
2.
Create a new application and give it a clear name, for example "Marketing Copilot agent" or "Nightly high-intent list sync". The service user uses this name, and it is how activity is identified.
3.
Under Acts as, select Dedicated service user. The redirect URI fields disappear because nobody signs in.
4.
Select the scopes the app needs. Choose the minimum. For example, an agent that answers questions about website visitors needs web_visits:read and companies:read. A job that also adds companies to a list needs lists:write. Add contacts:read only when it needs personal contact details.
Step 2: Store the credentials#
Copy the Client ID and Client Secret. Store the secret in your secrets manager. Do not put it in code, chat messages or logs.Anyone with both values can act as the app within its scopes.Step 3: Request an access token#
The app uses the OAuth 2.0 client credentials flow. Send the Client ID and Client Secret to the token endpoint. You can send them in the request body or in a Basic authorization header.Token endpoint: https://api.leadfeeder.com/v1/oauth/tokenCredentials in the request body:Credentials in a Basic header:Scopes are space separated. The token only gets the scopes you request that the app is also allowed to use. Request the scopes you need explicitly so the token stays as narrow as possible.The response contains an access token:{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "web_visits:read companies:read"
}
Access tokens last 1 hour. There is no refresh token. When a token expires, request a new one with the same call. Most OAuth libraries and automation tools do this for you when you select "client credentials".Step 4: Call the API#
Send the token as a bearer token. Start by listing the accounts the service user can reach:Most endpoints need an account_id. Use an ID from that response. For example, to read the companies that visited your website:Use it with the MCP server#
Tools such as Microsoft Copilot Studio and other agent platforms that support OAuth client credentials can connect to the Leadfeeder MCP server with the same Client ID and Client Secret. This is how a shared marketing agent can answer questions about your website visitors for the whole team.| Setting | Value |
|---|
| Server URL | https://mcp.leadfeeder.com/mcp |
| Token URL | https://mcp.leadfeeder.com/token |
| Grant type | Client credentials |
| Client authentication | Client secret in the body or in a Basic header |
| Scopes | The scopes you selected for the app |
Everyone who uses the agent shares the one connection. People are not asked to sign in.Account access#
A service user can use every account in your company, including accounts you create later. You do not need to update the app when a new account is added. It cannot reach accounts that belong to other companies.Manage and remove the app#
• Check the mode. The app details in Developer Access show whether the app acts as people who connect it or as a dedicated service user.
• Stop access. Delete the app. This removes the service user and revokes every token the app has issued. Use this when an agency contract ends.
• Secret exposed. Delete the app and create a new one, then update the credentials in your tool.Troubleshooting#
| Problem | What to check |
|---|
| The token request is rejected | Check the Client ID and Client Secret, and that the app was created as "Dedicated service user". Apps set to "People who connect it" are for sign-in flows. |
The API returns insufficient_scope | The token does not include the scope that endpoint needs. For example, adding companies to a list needs lists:write. Add the scope to the app and request a new token. |
The API returns invalid_token | The token expired or is invalid. Request a new one. |
| An account is missing | Call GET /v1/accounts with the token and confirm the account belongs to the same company as the app. |
| You cannot create a dedicated service user | You need the Applications Management permission. Ask a company admin. |
FAQ#
Can I switch an existing app to a dedicated service user?
No. Create a new app and choose "Dedicated service user".Does it use a seat or a license?
No. Service users do not appear in team management or seat counts.Does it still use credits?
Yes. Credits are charged to the account the call is made on, the same as for any other API or MCP call.Do I need a Service User for a personal script?
Not necessarily. A personal API key or a normal OAuth app is simpler for one marketer's own script. Use a Service User when more than one person depends on the connection, or when it must outlive any single employee.Is a Service User the same as an API key?
No. An API key belongs to a person. A Service User belongs to the app and is limited to the scopes you select.