API keys

An API key is a bearer secret that lets software you run - a script, an AI agent, the Bridget runner - access your ThoughtBridge account without your app login. Keys are created and managed in the app, never through the API itself: a key can never mint or revoke keys.

Create a key

1. In the app, go to Settings > API keys.
2. Choose Create key, give it a name you will recognize later (“Develop agent”, “Runner on the Mac mini”), and pick a scope. For read_write, also choose which projects it covers - see below.
3. Copy the secret immediately. It is shown once: ThoughtBridge stores only a hash, so the full key is never recoverable. If you lose it, revoke it and create a new one.

A key looks like tb_ followed by 48 hex characters. The keys list shows only a display prefix (tb_9f2c1a3b...), plus when each key was created and last used.

Scopes

Every key has exactly one scope, chosen at creation:

Scope	What it allows
read	List and read your thoughts and projects.
read_write	A full content-writing participant: everything read allows, plus creating captures, ticking tasks, editing the summary, adding notes and context links, uploading media, changing status, and moving a capture between its own projects.
runner	The Bridget runner surface (register, poll the queue, claim and update runs, answer project chats), plus the read endpoints. Runner keys cannot use the read_write mutations.

Scopes are fixed: to change a key’s scope, revoke it and create a new one. Keys work against a fixed allowlist of endpoints - see using the API for exactly which. Billing, key management, and every project/destination/runner administrative action (rename or delete a project, manage destinations, forget a runner instance) require the app’s first-party login and return 403 to a key, whatever its scope.

Scope to one, several, or all projects

A read_write key can be confined to specific projects: pick All projects, or check the ones you want when you create the key. A scoped key only sees those projects and their thoughts - creating a capture with it lands there automatically, and it can’t touch anything outside its set. Leave every project unchecked for a key that covers everything.

Settings > API keys shows each key’s scope alongside its projects, so you can tell at a glance what a key can reach. Runner keys can’t be project-scoped - they serve the whole bridge-it queue.

This is also how sharing a project works under the hood: a share is a read_write key scoped to exactly one project.

Writes propagate

Captures, status changes, task ticks, notes, and media added with a read_write key are not a side channel: they flow through the same pipeline as changes made in the app, so they sync to your destination’s files (thoughts-state.json, task checkboxes, the Media section) exactly like doing it in the app would. A capture created with a key carries a “Captured by” byline naming the key in the destination file.

Revoking a key

Revoke a key any time in Settings > API keys. Revocation is immediate: the key stops authenticating on its next request. Revoked keys stay in the list with their revocation time, so you keep the audit trail.

Keeping keys safe

• Store keys in an environment variable or a local .env file, never in code or a repository.
• Prefer .env or inline environment variables over command-line flags: command-line arguments are visible to other processes on your machine.
• One key per consumer. Give your develop agent and your runner separate keys so you can revoke one without breaking the other, and see per-key last-used times.
• Use the narrowest scope that works. Most read-only integrations never need read_write.