Team, roles and permissions

How access works

• An account is anyone who signs in. It belongs to a workspace through a membership with one role: Owner (exactly one per workspace), Admin, Member or Billing. The same account can hold a different role in each workspace it belongs to.
• Each workspace keeps its own roles matrix: which role holds which of fourteen permissions. The owner holds them all and cannot be edited, and two of them, workspace.delete and roles.manage, stay with the owner whatever the matrix says. A new workspace starts from the defaults below.
• The API checks every workspace request on the server: an account that is not a member gets 404, as if the workspace did not exist, and a missing permission gets 403. A suspended workspace keeps every read and refuses every write.
• The dashboard hides the sidebar rows and buttons a role does not include, and a page opened by its address shows Access required.
• A change to a member's role or to the matrix applies to that member's next request to the API. Their sidebar and buttons follow the next time the dashboard reads the workspace, at the latest on a reload.
• Platform staff (Platform admin and Support) are a separate set of roles across every workspace: see Platform administration.

The seeded roles and accounts

Forma Studio, the seeded workspace, uses the default matrix. Each role has one seeded account that signs in to the dashboard; the installation guide lists their sign-in details.

• workspace.read is what opens the Team, Roles and Settings rows, so every role, Billing included, sees the member list, the read-only matrix and the settings. The overview's projects, its weekly chart and the projects needing attention need projects.read. Its recent activity and the bell show every event to a role holding projects.read or audit.read; a role with billing.read and neither of those (Billing, as seeded) sees only the billing events, and any other role sees none. The full activity log and its export need audit.read.
• The workspace's billing email comes back only to a role with billing.read or billing.manage.
• Forma Studio has 8 members (an owner, an admin, five members and a billing contact) on the Pro plan's 10 seats, with two pending invitations and one archived project. The owner is also an admin of a second workspace, Monogram, which has its own owner, team, invitation and API key.
• yarn seed writes a workspace's matrix only when it has none, so running it again keeps the changes you made on the Roles page. Change every seeded password, or delete the sample accounts, before the dashboard is reachable from the internet.

• Installation

Every workspace permission

The Roles page groups the permissions under the labels below. The list is defined once, in back-end/src/modules/workspaces/constants/workspace-permissions.ts, with the defaults every new workspace starts from.

The Team page

/en/dashboard/team has two tabs, Members and Invitations, each with a search and a Role filter. Members are listed owner first, then by role and by when they joined.

• The owner's row has no actions: ownership moves only through Make owner.
• Removing someone takes them out of this workspace at once; their projects and tasks stay. Nobody removes themselves from this menu, and an admin may remove members and billing contacts but not another admin (the API answers 403).
• A removed member keeps their account and their other workspaces.

Invitations and seats

• Invite a member asks for an email address and a role, and lists what that role will be able to do. The person is mailed a link to /en/invitations/<token> that lasts seven days; without SMTP_HOST the message, link included, is written to the API's log.
• The invitation page shows the workspace, the role, the invited email (masked) and who sent it. Accepting needs the invited email signed in: someone new creates an account with that email first. An invitation for another email, an expired one or a revoked one is refused with its own message.
• Each plan has a number of seats: 3 on Starter, 10 on Pro and 30 on Scale. A pending invitation uses no seat; accepting one does. With no free seat, a new invitation is refused ("There is no free seat. Change the plan to invite more people."), and so is accepting one, checked in the same transaction so two people cannot take the last seat at once.
• Resend invitation makes a new link and a new seven-day expiry, once a minute at most and five times per invitation. Revoke invitation makes the link stop working.
• Inviting someone who is already a member, or who already has a pending invitation, is refused. Once a past-due workspace's grace period (BILLING_GRACE_DAYS) has run out, new invitations are refused until it is paid.

• Billing and plans
• Mail settings

The Roles page

/en/dashboard/roles shows the workspace's matrix: one row per permission, in the six groups above, and one column per role, each cell Allowed or Not allowed. The Owner column is locked, and the Delete workspace and Manage roles rows say Owner only.

• Only the owner changes it. Everyone else who holds workspace.read sees it read only: "Only the workspace owner changes what each role can do."
• Save changes first shows what each role gains and loses, then saves the whole matrix and writes one roles.updated event to the activity log. Reset goes back to the saved matrix.
• The four roles are fixed: a workspace cannot add a fifth. To give someone less than a role, take the permission away from that role, which changes it for everyone who holds it.

Ownership

• Make owner asks for the owner's password, then makes the chosen member the owner and the previous owner an admin, in one step. It is written to the activity log as ownership.transferred.
• The owner alone deletes the workspace, from Settings, with its name and their password.
• On the platform, an account that owns a workspace cannot be deleted until another member is made owner.

The routes behind these pages

:workspaceId is the workspace's public id, such as org_forma. Errors come back as codes: seat_limit_reached, already_member, already_invited, resend_too_soon, resend_limit_reached, owner_protected, workspace_owner_only and invalid_password among them.

• API reference

How the permission checks are built