Users, roles & organisations

Who can do what, and where. Permissions are named privileges collected into roles, roles are granted in an organisation, and an organisation's roles reach every organisation beneath it — never above.

Privileges and roles

A privilege is one named power: form:write, submission:read, billing:write. A role is a bundle of them that you grant to a person in an organisation. The privilege list is defined once by the platform and served to the interface, so what a screen offers and what the server enforces can never disagree.

Four built-in roles ship with every organisation and cover most needs:

Built-in roles cannot be edited — they are shared by every organisation on the platform. Create your own role when you need a different shape; it belongs to your organisation and can be assigned throughout its subtree.

You cannot grant what you do not hold

Creating a role, editing one, or assigning one is refused unless you hold every privilege involved. The refusal names exactly which privileges you are missing. In the roles screen, privileges you do not hold appear locked rather than hidden, so the boundary is visible rather than mysterious.

This is what stops an administrator of one corner of the tree minting a role that reaches further than they do. It applies to removal too: you cannot revoke a role wider than your own.

The organisation tree

Organisations nest. A role granted on an organisation grants its privileges there and in every organisation beneath it — which is what lets one administrator run a whole group without a separate assignment per entity. Nothing inherits upward or sideways: a role in a subsidiary says nothing about the parent.

Consequences worth knowing:

• A person can appear in a child organisation's user list via a role on an ancestor. Those grants are labelled with where they came from and can only be revoked there.
• Roles defined on a parent can be assigned in a child, but only edited where they were defined.
• Newly created child organisations become reachable after a session refresh — privileges are resolved when a session is issued.
• A person switches between the organisations they can reach from the account menu, or with Switch to on the Organisations page. Switching to somewhere unreachable is refused outright rather than quietly landing elsewhere.

The Organisations page shows the tree beside whichever organisation is open: its short name (what a partner types to share with it), who holds a role there and where each role came from, its recent history, and the verbs — rename, add a child beneath it, invite someone into it, switch to it. The Users page can likewise show another organisation's members when the tree has more than one, and everything done there — invite, grant, revoke — lands in the organisation on screen. Neither needs you to switch first.

Child organisations require the Business plan. Renaming an organisation never changes its short name, so partner shares and links keep working.

Inviting people

Invite by email address from Users (needs user:write), choosing the role they should hold — or from Organisations, straight into a child organisation. Two things happen depending on who the address belongs to:

• A new address gets an account with no password and an invitation link. Their role is granted immediately, so they arrive already able to work.
• An address that already has a Faldaro account is simply added, and told so. No password link is ever sent to a working account — a message inviting somebody to set a password on an account they already use is indistinguishable from a phishing attempt.

Invitation links last seven days, and issuing a new one invalidates any earlier unused link. Accepting sets a password of at least twelve characters, marks the address verified — following the link is the same evidence verification asks for — and ends any other sessions. An account showing as Invited is one nobody has accepted yet.

Seats are counted from the invitation, not the acceptance. An invited person occupies a seat while their link is outstanding.

Deactivating someone

Deactivating an account (user:write) does four things at once: sign-in stops working, every live session ends immediately, every API key that person created in this organisation is revoked, and their seat is freed. The account is archived rather than deleted, so the audit log keeps naming them accurately.

Keys they created in a different organisation are that organisation's to revoke — deactivation reaches only where you administer. Reactivating runs a seat check, so it can be refused if the organisation is now at its limit.

You cannot deactivate yourself, and you cannot remove your own last role in an organisation. An organisation whose only administrator locks themselves out has nobody left to undo it.

For a lost laptop or an offboarding checklist where the account should survive, ending sessions without deactivating is the lighter tool.

The audit log

Audit log (audit:read) records who changed what and when. It is append-only at the database permission level: the application cannot rewrite or delete an entry, and neither can anyone using it. How much history remains visible depends on your plan.

The log is grouped by day and can be narrowed by who made the change, by action, by the kind of thing changed, by one thing's whole history, and by date. Every row is itself a filter: press the person to see everything they did, or the thing to see everything that happened to it. Machine actors are named for what they are — an API key by its prefix, an agent by its id, the anonymous public surface as such — and api-key: or agent: in the Who box finds every change made through any key or any agent. Filters live in the address, so a narrowed view can be bookmarked or sent to a colleague, and each entry's recorded details open in place.

Sign-in events — successful and failed logins, lockouts, session revocations, refresh-token reuse — are recorded alongside, which is what makes "who got into this account, and when" answerable after the fact.