Skip to content

Tokens and authentication

An agent token is for a coding agent. An API token is for an application you build beside cawdev — a support tool that files what customers report, a product dashboard that shows where a card has got to, a bot that opens an issue when a health check fails. It reaches a small, versioned surface of its own under /api/integration/v1/, and it is deliberately narrower than an agent token: it files and it reads, and it can do nothing else on the projects it holds. It cannot decline a card, move a status, rename a section or write a plan, whoever minted it.

The section has four pages. This one is the token; Filing and reading cards is the five calls and the status vocabulary; Webhooks is how the platform tells your application when something moves, so it never has to poll; Git events is the other direction, GitHub or GitLab telling cawdev a branch merged. That one uses a project secret rather than a token.

Your settings → API tokens → Mint a token. Give it a label and tick the projects. There is no scope picker: each project ticked gets every one of the three scopes the token may hold that you may grant there —

Scope Lets the application You can grant it with the privilege
backlog:write File feedback See
cards:file File an issue at BACKLOG, NEW or CONFIRMED, or a roadmap card at BACKLOG, CONSIDERING or PLANNED — and nothing after that Edit cards
cards:read Read one card’s status, and what became of feedback See

— so a token you mint on a project where you can only see it holds the first and the last, and one minted where you can also edit cards holds all three. Privileges, and how a team’s members hold them, are on Team access and privileges.

The secret starts cawa_ and is shown once. Put it in your application’s configuration, never in its repository. The cawa_ prefix is what lets you tell an application’s token from an agent’s cawd_ in a log line.

Live tokens are listed on the page; revoked ones sit behind a disclosure. Agent tokens are listed on their own section and never here, so nothing appears twice.

Send the secret as a bearer token on every call:

Authorization: Bearer cawa_…

Every path is under https://app.cawdev.com/api/integration/v1/projects/<slug>/ — replace the host with your instance. The surface is versioned, unlike the console’s own API, because strangers are on it: what v1 answers today it will answer tomorrow.

An API token reaches these paths, the plain backlog filing path (POST /api/projects/{slug}/backlog, the same act as POST …/feedback here), and GET /api/agent/whoami. Every other path answers 403, naming the scope it would have needed — GET /api/projects/{slug}/roadmap with an API token is a 403 naming roadmap:read, which an API token can never hold.

One more door sits beside these and takes no token at all: the git events address that GitHub or GitLab posts to. Its credential is a per-project secret that a project owner generates, and it reaches nothing but that address.

Status Meaning
400 The request is malformed, or names a status the call does not accept. The body names what was wrong — a filing at IN_DEVELOPMENT is refused naming the statuses the call takes.
401 No token, or a revoked one.
403 The token holds no scope for this call on this project, named in the body.
404 A project the token does not reach, or a card or feedback id that does not exist there — deliberately not 403, so a token cannot enumerate projects it was not granted.
429 The filing cap, below. error: rate_limited.

The three filing calls — feedback, issues, cards — are capped at 60 per token per rolling minute, answered 429 with error: rate_limited. Reads are not capped. The cap is per API instance and resets when it restarts; it is a guard against a loop in your code, not accounting.

  • It cannot decide anything. Feedback it files stays PENDING until a signed-in person who can edit cards accepts or refuses it on the Feedback page; a card it files at PLANNED goes into development only when a person, or the project’s own rules, take it there.
  • It cannot manage its own webhook. The URL, the secret and the scope are set by the token’s owner in the console — a token that could point its own deliveries somewhere would be a credential turning itself into a feed.
  • It cannot read the roadmap, only one card at a time by ref, and only what the compact view carries.

The whole contract, with every schema, is the integration tag in the cawdev repository’s openapi.yaml.