Skip to main content
Every change in Work, from a person, an Agent or an outside system, goes through one path: sign in, check permission, check the input, write the audit record, then do it. No screen or Agent has a back door.

​
Members

A member is someone who can act in your organization.
  • The person who creates the organization is its Owner. An Owner has every permission.
  • Add a person by email (POST /v1/members with email, kind and displayName), or invite them with POST /v1/invitations. The invited person accepts the invitation to join.
  • A new organization starts with POST /v1/signup (an email and an organization name). After you sign in with Worksong, POST /v1/session links your login to your member. GET /v1/me returns who you are and your role.
  • Remove a member to take them out for good.
  • Suspend a member to stop them without deleting anything. Reinstate brings them back. A suspended member’s open realtime connections are closed.
  • Agents are members too. See Agents in Work.
  • Positions (a title and who it reports to) and responsibilities (a line of text per member) describe your organization chart. They do not grant any permission.

​
Authority

Authority says what a member may do. There are three levels, and each includes the one before: An authority is given on one board or on the whole organization. A member with no authority can do nothing. You can only give authority up to what you hold yourself. Actions are checked by their name: those that start with item. need Write, and all others, such as email.send or calendar.event.create, need Manage. An Agent that proposes outside actions therefore needs Manage.

​
Gates

A gate holds an action until a person approves it.
  • Action pattern: the action it covers, for example email.send.
  • Board: one board, or all.
  • Approver: the member who decides.
  • When (optional): only when a column has a given value, { "columnId": ..., "equals": ... } or "in": [...].
When an action matches a gate, the API answers 202 with pending_approval, and a proposal is created. The approver approves or rejects it in Approvals. If nobody has set up a gate for the action, the action runs at once. A template that lets an Agent propose something must therefore also install its gate. Resolved proposals stay on the item’s timeline with who decided.

​
Limits

Limits cap a member. Leave a field empty for no limit. Read what is left with GET /v1/limit-status. A limit never grants anything. It only narrows what authority and gates allow.

​
API tokens

A token lets a script or an outside tool act as a member. It is a credential of that member, not a new kind of user.
  • Issue it with the member, a name, a verb and a board (or all boards).
  • The token can do at most what both the member and the token’s own verb and board allow.
  • The secret is returned once, when you create the token. Lists show only the name, member, verb, board and whether it is revoked.
  • Revoke a token at any time.
  • You cannot issue a token beyond your own authority, or beyond the member it acts as.
Tokens are not tied to the web sign-in. See the Work API.

​
Audit

Every change, and every refusal, is written to an append-only audit log before it happens. Each entry names the member and how they signed in (login or token). Members with Manage can read it from Audit. Nobody can edit or delete an entry.

​
What each person can see

​
Notifications

GET /v1/notifications lists what Work sent you, such as a mention, an assignment, or an Agent that reached its limit (agent-limit-reached). Mark them read with POST /v1/notifications/read. Source: worksong-ai/worksong:services/work/src/Boardy.Authority@9f0684f, worksong-ai/worksong:services/work/src/Boardy.ActionBoundary@9f0684f, worksong-ai/worksong:services/work/src/Boardy.Api/Program.cs@9f0684f, worksong-ai/worksong:services/work/CLAUDE.md@9f0684f. Docs version: Worksong 2.0 with Work 1.2.