Service Accounts & Scopes
A Service Account is a set of credentials your organization uses to connect kenbun to automation tools like n8n, Zapier, or your own backend. Unlike a Personal Token, a Service Account belongs to your organization rather than to one person, so it keeps working when team members come and go.
Scopes make a Service Account least-privilege. Instead of handing an automation a credential that can do everything, you grant only the access it actually needs. A workflow that just needs to score leads can be given a credential that can do nothing else. If that credential ever leaks, the damage is limited to the few things you allowed.
Why Scopes Matter
Most automations only do one job. An n8n workflow that scores incoming leads does not need to delete accounts, edit your scoring rules, or read your segments. Scopes let you match the credential to the job:
- Smaller blast radius. A leaked credential can only do what its scopes allow.
- Clear intent. Anyone reviewing your credentials can see exactly what each one is for.
- Safer sharing. You can hand a vendor or contractor a credential that is read-only, or limited to a single area.
If you grant no scopes, the credential has full access (the original behavior). This keeps any credential you created before scopes existed working exactly as it did. New credentials should be scoped to just what they need.
How Scopes Work
Each scope is made of an access level and an area:
- Access level:
read(view only) orwrite(create, update, and delete). - Area: the part of kenbun the scope covers, such as
leadsorscoring.
So write:scoring lets a credential create, update, and delete scoring configuration and score leads, while read:leads only lets it view leads. A credential can hold any combination of scopes.
When a Service Account has one or more scopes, it is restricted to them. Any request outside its scopes is refused with an insufficient_scope error. When it has no scopes, it has full access.
Available Scopes
| Area | What read: grants | What write: grants |
|---|---|---|
| scoring | View scoring rules, levels, mappings, filters, and lead scores | Create, update, and delete scoring configuration; score leads |
| leads | View leads, lead activity, and search | Create, update, merge, and delete leads |
| accounts | View accounts, sessions, and account details | Create, update, and delete accounts |
| deals | View deals and deal attribution | Create and update deals |
| events | View events and imports | Send events, run imports |
| segments | View segments and their membership | Create, update, and delete segments |
| triggers | View triggers and their history | Create, update, and delete triggers |
| integrations | View integration connections and credentials | Connect integrations and manage credentials |
| settings | View organization, unit, member, and usage settings | Change organization, unit, member, and usage settings |
The live list of scopes (with descriptions) is always available in the app when you create a credential, so the choices you see there are always current.
The integrations area also covers credential management itself. A credential needs write:integrations to create or change other credentials. This prevents a low-privilege credential from quietly upgrading itself by minting a more powerful one.
Create a Scoped Service Account
- Go to Settings → Integrations → Service Accounts.
- Click Create Credential.
- Give it a clear name that describes its job, for example
n8n Lead Scoring. - Select the scopes the integration needs. For a workflow that only scores leads, choose
write:scoring(addread:scoringif it also needs to read scores back). - Click Create.
- Copy the Client ID and Client Secret shown on screen and store them in your automation tool. The secret is shown only once and cannot be retrieved again.
To see what an existing credential can do, open the same page. Each credential lists the scopes it was granted.
Use a Service Account
Service Accounts authenticate with HTTP Basic Auth. Combine the client ID and secret as client_id:client_secret, base64-encode them, and send them in the Authorization header.
curl -X POST "https://api.kenbun.io/scoring/score" \
-H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
-H "Content-Type: application/json" \
-d '{ "lead_id": "abc-123" }'
In n8n, Zapier, or a similar tool, choose Basic Auth as the authentication method and enter the client ID as the username and the client secret as the password.
What Happens When a Scope Is Missing
If a scoped credential tries to do something outside its scopes, kenbun refuses the request and returns an insufficient_scope error. For example, a credential with only write:scoring that tries to list leads will be refused.
When that happens, you have two choices:
- Add the missing scope to the credential, or
- Create a separate credential for the other task.
Creating a separate, narrowly scoped credential per integration is usually the safer choice.
Service Accounts vs. Personal Tokens
| Service Account | Personal Token | |
|---|---|---|
| Belongs to | Your organization | One person |
| Survives a team member leaving | Yes | No |
| Best for | Automation and integrations (n8n, Zapier, backend systems) | Personal scripts and AI assistants |
| Authentication | HTTP Basic Auth (client ID and secret) | Bearer token (kbn_pat_...) |
| Supports scopes | Yes | Yes |
Personal Tokens support the same scopes. The difference is ownership: use a Service Account for anything that should outlive any one person.