Module 10 — Build and Extend · Lesson 10.5
The REST API, API Keys and the CLI
Driving Kavanah from a script or a terminal, and the key model that makes it safe
~11 min
What you'll learn
- Mint and revoke an API key, and store it correctly
- Explain what permissions a key carries
- Call the REST API with bearer authentication
- Use the CLI safely, including against production
Everything the interface does, the API does. That makes Kavanah scriptable — for a migration, an integration, a report generator, or an agent session driving your workspace from a terminal. The permission model is the part worth understanding first, because it is what determines the blast radius of a leaked key.
Minting a key
Settings → API Keys, admin only. Name the key for the integration that will use it and create it.
The token — it starts with `kvn_live_` — is shown exactly once, at creation. Only a hash is stored, so it cannot be retrieved later. Copy it immediately into wherever it is going to live.
If a key is lost or compromised, revoke it here and mint a new one. Revocation is immediate.
Name keys for their purpose. 'Reporting script' and 'Zapier' are useful names when you are deciding what to revoke; 'key 1' is not.
What a key can do
A key is scoped to the workspace, and it inherits the RBAC of the user who minted it.
That second half is the important one. A key minted by an admin can do what that admin can do. A key minted by a member is bounded by that member's permissions.
So the principle is: mint keys as the least-privileged user who can do the job. A reporting integration does not need an owner's key, and giving it one means a leak is a workspace-wide problem rather than a read-only one.
Authentication is a header: `Authorization: Bearer kvn_live_...`. No cookies and no CSRF token — it is designed for server-to-server use.
The API itself
The API is documented with an OpenAPI specification, and there is a full endpoint reference in the docs.
The shape is what you would expect: resources for tasks, projects, clients, deals, time entries, reports, planning, members and the agent, with the usual verbs.
One surface worth knowing about: you can execute agent tools over HTTP directly, by name, rather than going through a chat turn. That gives you deterministic access to the same capabilities the agent has — useful when you want the capability without the model deciding.
Be aware that route is deliberately fail-closed: where a workspace's action policy would park an action for approval, the direct execution returns a parked response rather than performing it. That is correct, and it means a script cannot use the tool route to bypass governance.
The CLI
There is a zero-dependency command-line interface that drives the same API using a workspace API key. It is the fastest way to poke at the product, and it is designed to be usable from an agent session as well as by a person.
Two things to know before running anything.
Its default base URL is production. A command you run to try something out runs against your live workspace unless you point it elsewhere.
And destructive commands — every delete, cron triggers, admin operations, bulk task writes, member deprovisioning, resyncs — refuse to run against a non-local base URL without an explicit confirmation flag. That guard exists because a convenience tool that fans out across a workspace is exactly the shape of an accidental incident.
Respect both. Point at a local instance when experimenting, and read what a destructive command will do before adding the flag.
What to build with it
The things people actually build, in rough order of frequency.
Migrations: importing tasks, clients or history from a previous system, once.
Reporting: pulling data out into a warehouse or a spreadsheet that someone else's process depends on.
Integrations: connecting a system Kavanah does not have a card for.
And operational scripts: the small recurring things that are not worth an app and are worth automating.
For anything conversational, use the agent rather than the API. The API is for determinism; the agent is for judgment, and using the wrong one for either is more work than it needs to be.
Get programmatic access
- 1
Mint a key as the least-privileged user who can do the job
Settings → API Keys, admin only. The key inherits the minting user's permissions, so this choice is the blast radius.
- 2
It is shown exactly once; only a hash is stored. There is no way to retrieve it later.
- 3
The docs carry the full endpoint listing and the OpenAPI specification.
- 4
Point the CLI at a local instance while experimenting
Its default base URL is production, and destructive commands need an explicit flag against a remote one.
What to watch
- Key inventory
- How many active API keys exist and whether each has a known owner and purpose.
- Healthy signal: Every key named, owned and in use. An unattributed key is a standing grant nobody can reason about.
- Key privilege level
- Whether keys were minted by the least-privileged user that could do the job.
- Healthy signal: Always. An owner-minted key for a read-only script turns a leak into a workspace-wide problem.
- Key age
- How long keys have been in circulation without rotation.
- Healthy signal: Rotated on a schedule you set. There is no expiry to rely on, so this is a habit rather than a feature.
Key takeaways
- ·Keys are admin-minted, shown once, and inherit the minting user's RBAC — mint as the least-privileged user.
- ·Authenticate with an Authorization: Bearer header; no cookies or CSRF needed.
- ·Agent tools can be executed directly over HTTP, and that route is fail-closed against the action policy.
- ·The CLI defaults to PRODUCTION, and destructive commands refuse to run remotely without an explicit flag.
- ·Use the API for determinism and the agent for judgment.
Module 11 is the administration layer: settings, money, security, provisioning and recovery.