Authentication
Create a scoped API token in the console and send it as a bearer token.
The klerc API uses bearer tokens. You create a token in the console, choose what it may do, and send it with every request.
Create a token#
- Open Settings → API Tokens.
- Choose Generate token, name it after the integration it's for, and pick its scopes.
- Copy the token when it's shown. Live tokens start with
wk_live_.
The token list shows each token's scope summary, when it was last used and whether it expires. Delete a token to revoke it immediately.
Send it#
Put the token in the Authorization header:
curl https://api.klerc.co/api/v1/objects \ -H "Authorization: Bearer $KLERC_TOKEN"A missing or invalid token returns 401.
A token never outgrows its owner#
A token can never do more than your account is allowed to. Every request is bounded twice:
- by the scopes you picked for the token;
- by your live permissions — your role, teams, the hierarchy and field-level security, as they are at the moment of the request.
If your access to a field or an object changes, your tokens change with it. If you leave the organisation, your integrations lose access too.
Scopes#
Scopes are feature:action. Each operation in the reference names the one it needs.
| Feature | Scopes |
|---|---|
| Objects, records and lists | objects:view, objects:use, objects:manage |
| Query | query:run |
| Flows | flows:view, flows:use, flows:manage |
| Tasks and notes | tasks:view, tasks:use, notes:view, notes:use |
| Inbox | inbox:view, inbox:send |
| Team inbox | team_inbox:view, team_inbox:send, team_inbox:manage |
| Reports and dashboards | reports:run, reports:create, dashboards:view, dashboards:create, dashboards:manage |
| Calendars and forms | calendars:view, calendars:use, forms:view, forms:manage |
| Workflows and chatbots | workflows:view, workflows:manage, chatbot:view, chatbot:manage |
| Agents and secrets | agents:view, agents:manage, secrets:view, secrets:manage |
| Knowledge base | knowledge_base:view, knowledge_base:create, knowledge_base:manage, knowledge_base:share, knowledge_base:export |
| Integrations and audit logs | integrations:view, integrations:manage, audit_logs:view, audit_logs:export |
As a rule of thumb: view reads, use creates and edits day-to-day data, and manage changes configuration such as schemas, workflows and forms.
A token without the scope an operation needs gets 403 — the same status as a call to a feature that's switched off. The error message says which.
Molly's token#
Every user has a token named Molly. It's what the assistant uses to act on your behalf, and it's bound by the same rule: never more than you.
Keeping tokens safe#
- Keep tokens on servers. Never ship one in a browser or mobile app.
- Give each integration its own token with the fewest scopes it needs.
- Rotate tokens when people who knew them leave, and delete ones you no longer use.