Concepts
Task Access Model
How task access control works in Buildd
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
Workers can have one of two account levels:
| Level | Capabilities |
|---|---|
worker | List, claim, execute, and complete tasks. Search and save memory. |
admin | All worker capabilities + create tasks, reassign, send instructions, manage schedules and skills. |
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, level (worker|admin),
apiKey, teamId, authType (api|oauth)
-- Workspace access control
account_workspaces
accountId, workspaceId, canClaim, canCreateAccess Control
Workspace Access
workspaces.accessMode: 'open' | 'restricted'
open: Any token in the team can claim tasks
restricted: Only accounts in accountWorkspaces with canClaim=trueTask 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