api keys

an API key (brk_…) is how your code proves which project it's allowed to touch. every SDK and HTTP call sends one as Authorization: Bearer brk_…. keys are per-project, so a key for one project can never reach another.

create one in the dashboard

1
open your project's api keys page
sign in at briven.tech, open the project, and click api keys. you need the admin role on the project to create or revoke keys.
2
click new key, name it, pick a role
give it a name you'll recognise later (e.g. prod-server or vercel-preview) and choose a role (see below). you can also set an optional expiry in days — after which the key stops working on its own.
3
copy the key now — it is shown only once
the full key (brk_…) is revealed a single time, right after you create it. briven only stores a hashed fingerprint, so it can never show you the key again. copy it straight into your secret manager or .env file before you close the dialog.

roles (what a key is allowed to do)

each key is scoped to a role. pick the least powerful one that gets the job done — that way a leaked key does the least damage. you can only issue a key at or below your own role, and owner is never assignable to a key.

viewer · read-only

read data and run read-only functions. safe to ship in a browser bundle. cannot write, deploy, or change settings.

developer · read + write

everything viewer can, plus invoke write functions and deploy. this is the day-to-day key for your server / CI. keep it server-side.

admin · full project control

everything developer can, plus manage the project, its members, and its keys. use sparingly.

one-time reveal

when you create a key, the API returns the plaintext exactly once and never again — only a hash is kept. if you lose a key, you can't recover it; create a fresh one and revoke the old. there is no “show key” button anywhere by design.

keep keys secret

never commit a key to git. put it in .env (git-ignored) or a secret manager.
only a viewer(read-only) key may live in browser / client code — and even then it's public, so scope it tightly. developer and admin keys are server-side only.
rotate on a schedule and whenever someone leaves the team. give each environment/service its own named key so you can revoke just one without downtime elsewhere.
revoking a key takes effect immediately — the next request with it is rejected.

managing keys over the API

the dashboard is built on these endpoints (all require a dashboard session with the admin role on the project):