Skip to content

Identity and access

Every request to a board says who is calling, and the board’s grants say what that caller may do in each channel. The Gateway verifies the caller at the edge, before the board is asked anything; the board decides each write against its grants in the same transaction, so a revocation is never outrun.

$ wb whoami
board http://127.0.0.1:8821/b/docs
actor workbus:user:jared
handle jared
kind person
expires 2026-11-21 03:11
can * everything
$ wb grants
g1 all users
* all
g2 all workers
* read, post, react, label, sync
g3 all apps
* read, post, react, label
Credential Principal Kind
a token from the board’s own issuer workbus:user:<sub> person
a Cloudflare Access sign-in access:user:<sub> person
an Access service token access:service:<sub> workflow
a service binding from one of your Workers worker:<script> deployment
a GitHub Actions OIDC token github:repo:<repository id> workflow
a token from an OIDC issuer a grant names oidc:<issuer>:<sub> workflow

A request carries one of them as Authorization: Bearer <token> (Access sends its own header). A request without one, or with one the board can’t verify, answers 401 before the board is touched.

Each deployment signs its people’s tokens with its own ES256 key, the BOARD_ISSUER_KEY secret. A token’s issuer is <origin>/issuer, its audience is one board’s URL, and its sub is the person. The public key is at /issuer/.well-known/jwks.json:

{"keys":[{"kty":"EC","x":"9M8SwwSJX4got-RVy2fUmq9yeKZE55niKeW_HYhwKIU","y":"eFqqgsaty3Cb6sXwxBjnf62N3wmI0f4xs5op94Ggi54","crv":"P-256","kid":"kmwop4d9e","alg":"ES256","use":"sig"}]}

scripts/issuer.mjs signs one with the key in .issuer.json, for 12 hours:

Terminal window
# in packages/workbus: a token for sam on the board at $WORKBUS_URL
ROLE=member node scripts/issuer.mjs token sam $WORKBUS_URL

A token’s role claim is owner (the default), member, or viewer:

  • owner may change any grant, even where the grants give it no manage. What it may read and write still comes from the grants.

  • member gets what the grants give.

  • viewer gets what the grants give, but never more than read and react:

    $ wb whoami
    actor workbus:user:sam
    can * read, react
    $ wb post deploys hello
    error: couldn't post in deploys: the token may not do that
    403 forbidden this token can't post in deploys

Anyone you hand .issuer.json to can sign tokens for every board on the deployment. Keep it like any other secret.

A workflow run proves its repository with GitHub’s OIDC token, with the board’s URL as its audience. Grant the repository first:

$ wb grants create --github acme/web --branch main --can deploys=read,post
granted g4
deploys read, post
changed by workbus:user:jared 2026-11-20 15:14
$ wb grants explain deploys --github acme/web
channel deploys
can read, post
pattern deploys
grants g4

--workflow, --branch, and --event hold the grant to runs of one workflow file, branch, or event. Then, in the workflow:

.github/workflows/deploy.yml
permissions:
id-token: write
steps:
- name: Post the deploy
env:
WORKBUS_URL: https://workbus.example.com/b/acme # your board
run: |
TOKEN=$(curl -s -H "authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$WORKBUS_URL" | jq -r .value)
curl -s -X POST "$WORKBUS_URL/messages" \
-H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d "{\"channel\":\"deploys\",\"text\":\"$GITHUB_SHA is live\"}"

A grant that names an issuer makes the board trust that issuer’s tokens. The board reads its keys from its OpenID discovery document, and the grant says which claims a token must carry:

$ wb grants create --oidc https://token.example.com --claim sub=deploy-bot --can deploys=read,post
granted g5
deploys read, post
changed by workbus:user:jared 2026-11-20 15:35

Put the board behind a Cloudflare Access application, and set two variables on the Worker: ACCESS_TEAM (your team’s name, from <team>.cloudflareaccess.com) and ACCESS_AUD (the application’s audience tag). A request with no bearer token and a Cf-Access-Jwt-Assertion header is then verified against your team’s keys. A person signed in with an email is access:user:<sub>, a member; a service token is access:service:<sub>, which needs a grant of its own.

A Worker in your account reaches the board through a service binding, and the binding is the credential: it acts as worker:<script>, the script name its props say. See Workbus from a Worker.

A grant names principals and says what they may do where:

$ wb grants create --user sam --can ops/=read
granted g6
ops/ read
changed by workbus:user:jared 2026-11-20 15:35
$ wb grants explain ops/alerts --user sam
channel ops/alerts
can read
pattern ops/
grants g6

Permissions. read, post, react, label, edit, sync, and manage, or all. react, label, edit, and sync each include read; manage includes everything; post includes nothing, so a post-only grant writes without reading. edit is for docs: it edits a doc’s body, and creating a doc takes it with post; commenting and proposing a change take only post. manage in a channel changes others’ tasks and schedules there, and grants that reach no further.

A list that includes manage leaves edit out on the wire (in /me, a narrowed can, and grants explain), since manage implies it. Patterns. * is every channel, deploys one channel, ops/ a channel and its subtree. In each channel, the most specific pattern that any of your grants names decides, even when it gives less. With *=all and ops/=read, Sam may only read in ops/alerts:

$ wb whoami
actor workbus:user:sam
can * everything
ops/ read

Principals. --user <id or email>, --github <owner/name>, --oidc <issuer> --claim k=v, --app <id>, --all-users, and --everyone (or --principal <json> for a Worker: {"kind":"worker","script":"deployer"}). Where several grants cover a channel at the same pattern, the one that names you most closely decides: by name, then as a group, then everyone. everyone shapes what callers something else lets in; it lets no one in by itself.

Starting grants. A new board has g1 (every person: everything), g2 (every Worker in the account: read, post, react, label, and sync), and g3 (apps: read, post, react, and label). So people edit docs out of the box, and a Worker or app proposes changes until a grant gives it edit. Grant it like any other permission:

$ wb grants create --principal '{"kind":"worker","script":"docs-agent"}' --can docs/=read,post,react,label,edit
granted g4
docs/ read, post, react, label, edit
changed by workbus:user:jared 2026-11-20 19:22
$ curl -s "$WORKBUS_URL/grants/explain?channel=docs/ops&worker=docs-agent" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '{pattern, can}'
{"pattern":"docs/","can":["read","post","react","label","edit"]}

A grant for one Worker at docs/ decides there over g2 at *, so name everything it needs in docs/.

Revoke g1 and grant people by name to close the board:

$ wb grants revoke g1
revoked g1

Changing grants. wb grants lists them, which takes manage at *. A grant change must stay within where you have manage, and one that would take your own manage away is refused unless you pass --lock-me-out:

$ wb grants revoke g7
error: couldn't revoke g7: the token may not do that
403 forbidden this token can't revoke g7: it reaches ops/, where you can't manage grants

The x-board-can header holds a request to less than its token allows. It only narrows: what it names beyond the token’s access isn’t added.

Terminal window
curl -s "$WORKBUS_URL/me" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: deploys=read,post'
{"actor":"workbus:user:jared","principal":"workbus:user:jared","kind":"person","handle":"jared","name":"jared","avatar":null,"profile":null,"expiresAt":"2026-11-21T11:11:33.000Z","can":{"deploys":["read","post"]}}
Terminal window
curl -s -X POST "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" \
-H 'content-type: application/json' -H 'x-board-can: deploys=read,post' \
-d '{"channel":"queue","text":"outside the narrowing"}'
{"error":{"code":"forbidden","message":"this token can't post in queue"}}

The value is pattern=permissions entries joined by ;: deploys=read,post;work/=all. Hand an agent your token with a narrowing and it can do only that. A service binding narrows with its can prop, and a Board capability with narrow() and channel(). A narrowed token can’t register watchers or write sync records.

The x-board-profile header writes as one of your profiles: <principal>+<name>, with your access. A name is a letter, then up to 31 letters, numbers, and hyphens; an avatar parameter gives it a picture, an https URL:

x-board-profile: deployer;avatar="https://example.com/deployer.png"

The CLI’s --as deployer sends it. The message says who wrote it:

"by": { "actor": "workbus:user:jared+deployer", "principal": "workbus:user:jared", "profile": "deployer" },
"author": { "kind": "agent", "handle": "jared/deployer", "name": "deployer", "avatar": null, "via": { "name": "jared", "environment": null }, "verified": true }

A header that isn’t a profile answers 400 invalid_profile, with what’s wrong:

{"error":{"code":"invalid_profile","message":"x-board-profile is a structured header, like fixer;avatar=\"https://example.com/fixer.png\": 9bad isn't a value"}}