Task Access Model

Overview

Buildd separates Dashboard Users (task creators/managers) from Workers (task executors). All resources are scoped to teams, and access is controlled at the workspace level.

Roles

Dashboard Users

Authenticate via Google or GitHub OAuth
Belong to one or more teams with roles (owner, admin, member)
Create and manage workspaces
Create and prioritize tasks
View worker progress and results
Manage billing and settings

Workers (Machine)

Authenticate with API tokens (bld_xxx)
Claim and execute tasks via API or MCP server
Report progress and submit results
Scoped to a team via the account's teamId

Machine accounts have one of three levels — trigger, worker, or admin. Each is a superset of the one before it:

Level	Capabilities
`trigger`	File and read only: list/read tasks, create tasks and artifacts, emit events, read schedules. Cannot claim or execute.
`worker`	All of `trigger` + claim, execute and complete tasks, open/merge/close PRs, update tasks and artifacts, read failure and usage analytics.
`admin`	All of `worker` + create tasks by schedule, send agent instructions, manage schedules, skills, missions, initiatives, workspaces, secrets and releases.

The level is enforced twice on the MCP surface: out-of-level actions are omitted from the advertised action enum, and the handler rejects them again with {"error":"forbidden", …}. See MCP Server for the per-level action lists.

The default level depends on which route mints the key, and they disagree:

Path	Level when `level` is omitted
`POST /api/accounts`	`worker`
Direct DB insert (column default)	`worker`
`POST /api/auth/device/code`	`admin`
`GET /api/auth/cli`	`worker` for the `runner` client; `admin` for `cli`, `mcp` and `agent`
OAuth-authenticated request	forced to `admin`

So a key created through the device-auth or CLI flow without an explicit level is an admin key. See Device Authentication.

Data Model

-- Teams (top-level organization)
teams
  id, name, slug, plan

-- Team membership
team_members
  teamId, userId, role (owner|admin|member)

-- Dashboard users (OAuth)
users
  id, email, name, googleId, githubId

-- Worker accounts (API tokens)
accounts
  id, name, type (user|service|action),
  level (trigger|worker|admin) DEFAULT 'worker',
  apiKey, teamId, authType (api|oauth)

-- Workspace access control
account_workspaces
  accountId, workspaceId, canClaim, canCreate

Access Control

Workspace Access

workspaces.accessMode: 'open' | 'restricted'

open:       Any worker- or admin-level token in the team can claim tasks
restricted: Only accounts in accountWorkspaces with canClaim=true

Task Visibility

Dashboard users:  See all tasks in their team's workspaces
Machine workers:  See tasks from permitted workspaces (via API/MCP)

Auth Model

Buildd supports two authentication types with different billing strategies:

Auth Type	Billing	Limits
`api`	Pay-per-token	`maxCostPerDay`, tracked via `totalCost`
`oauth`	Seat-based	`maxConcurrentSessions`, tracked via `activeSessions`

Check the authType field on the account to determine which limits apply.

Worker Flow

1. API key created in dashboard (scoped to team)
2. Account linked to workspace (if restricted)
3. Worker calls claim API with token
4. Worker executes task on assigned branch
5. Worker reports progress at milestones
6. Worker creates PR and marks task complete

Task Access Model

On this page