Structure and roles

By the end of this page you will be able to:

1. build your organization’s structure out of units;
2. pick a role for each person;
3. predict which actions the server allows for that role and which it refuses.

Example: at Northwind, Anna is head of the Backend unit, Ben is a member of that unit, Vera is a contractor, Grace from internal control is an auditor, and the founder David is the admin.

Units

The structure is a tree. Its root is created together with the organization: a “Legal entity” node carrying the organization’s name.

Type in the account	API value
Holding	holding
Legal entity	legal_entity
Branch	branch
Department	department
Unit	unit
Team	team

Tree rules the server enforces:

• only the admin changes the structure;
• names are 1 to 120 characters;
• the root cannot be moved or deleted;
• a node cannot be moved inside itself (“A unit cannot be moved inside itself.”);
• only an empty node can be deleted: remove nested units first, then move the people out.

Northwind (Legal entity)               ← root, admin David
└── Engineering (Department)
    ├── Backend (Unit)                 ← head Anna
    │   ├── Ben (member)
    │   └── Vera (contractor, 60 days)
    └── Platform (Team)
Grace (auditor) is attached to the root

1. Switch to the organization and open the Structure tab.

2. In “Add unit”, choose the parent node, the type and a name, then click “Create”.

3. Use the buttons next to a node to rename or delete it.

Roles

Every person in the organization is attached to one node of the tree and has one role. Both are set in the invitation; later the admin can change them on the People tab.

Role	API value	In short
Admin	org_admin	Runs the organization
Head	unit_head	Sees their subtree and can offboard people in it
Member	member	Works with memory
Contractor	contractor	Only own and project records, time-limited access
Auditor	auditor	Audit log without memory content

What each role can do

Action	Admin	Head	Member	Contractor	Auditor
View the structure	yes	yes	yes	yes	yes
Change the structure	yes	—	—	—	—
People list	everyone	own subtree and self	self only	self only	self only
Invite; change role, node and access term	yes	—	—	—	—
Issue a key for themselves	yes	yes	yes	yes	—
See keys	every key in the organization (no secrets)	own	own	own	—
Revoke keys	any	own	own	own	—
Offboard with knowledge handover	anyone but themselves	people in the subtree they head, except admins	—	—	—
Read and write records	yes	yes	yes	own and project only	—
Audit log	yes	—	—	—	yes
Plan and seats	yes	—	—	—	—

What each role reads:

• Admin, head, member — their own records, organization-wide records, project records, and “unit” records of their own node and the nodes above it. The admin and heads also see “unit” records anywhere in the subtree they head. Nobody, the admin included, sees the drafts (“author only”) of other people who still work there.
• Contractor — only their own records and records with “project” visibility. Their new records get “project” visibility straight away.
• Auditor — no records at all. An auditor cannot issue a key (auditor_has_no_keys) and cannot write to memory; the audit log is what they get.

Caution

An organization always needs at least one active admin. The server will not demote or offboard the last admin — “The organization needs at least one admin.” You also cannot offboard yourself.

Tip

Attach a unit head to the unit’s node, not to the department’s: a head sees “unit” records across the whole subtree of their node and can offboard people inside it.

Common server responses

Code	When	What to do
org_admin_required	The action is admin-only	Ask the admin
not_allowed_to_offboard	A head tries to offboard someone outside their subtree, or an admin	The admin offboards
last_admin	Demoting or offboarding the last admin	Appoint a second admin first
node_has_children, node_has_members	Deleting a non-empty node	Move or delete what is inside
access_expired	The person’s access term has ended	The admin extends it

The full list is in Errors.

Next steps

Record visibility How roles combine with each record's visibility.

Invitations and keys Give a person a role and access.

Offboarding How a head hands over a leaver's knowledge.

Contractors Access terms and extensions.