Settings — Permissions & Access Rights

This page is the single source of truth for access rights in Athenty. It explains, model by model and action by action, who is allowed to do something and why — so you can answer questions like “why can a bookkeeper apply a client credit but not close a period?” or “what does the Compliance Management add-on actually unlock?” without guessing.

Every gate below is enforced server-side in the API. The UI hiding a button is never the only guard — the platform re-checks the actor’s role, add-on toggles, and matter involvement on every request.

The access model has four layers, applied in order:

Layer	What it is	Example
1. Base role	The org-wide tier every user has exactly one of	Owner / Admin / Manager / General
2. Add-on toggle	A per-user capability switch layered on top of the base role	Bookkeeping Management, HR Management, Compliance Management
3. Matter-level access	Per-matter elevation and the org-wide Matter Planner subscription	Matter Responsible, Matter Planner
4. Client-portal tier	Per-participant, per-matter capabilities for external clients	Communications / Documents / Uploads / Billing / Approvals

1. Base roles

Every staff member has exactly one base role. Roles are ordered low-to-high — each higher role is a superset of the one below it.

Role	Rank	What it grants
Owner	highest	Full platform access (wildcard `*`) — everything, including billing and dangerous/irreversible deletions. One or more per tenant.
Admin	high	Settings + team management, accounting control, HR/AML settings, matter management. No billing. Cannot promote anyone to Owner.
Manager	mid	Matter-responsible work: create/decide requests, manage matters, manage verification / document / notification templates, manage notaries.
General	base	Day-to-day work: create requests, view own requests, view notaries. The default role for new staff.

Roles are managed under Settings ▸ Access Levels. The platform refuses two transitions to prevent lockout: you cannot demote yourself from Owner, and the last remaining Owner cannot be demoted by anyone. To rotate ownership, promote a new Owner first, then demote the old one.

2. Add-on capability toggles

Add-ons are per-user boolean switches that grant a focused bundle of authority without promoting the user to Admin. They are all granted only by an Owner or Admin, are audit-logged on grant/revoke, and are checked in code as actor.role === 'owner' || actor.role === 'admin' || actor.flag === true (where flag is the add-on’s code flag).

The point of an add-on is blast-radius reduction: a bookkeeper, HR specialist, or compliance officer gets exactly the powers they need for their job and nothing else.

Add-on	Code flag	Unlocks	Why it exists as an add-on (not a role)
Bookkeeping Management	`bookkeepingMgmt`	Day-to-day accounting control: credit memo / write-off, refund, sweep-to-trust, operating fund transfers, matter credit splits — see the accounting matrix below.	Lets a non-Admin bookkeeper run daily accounting so the books aren’t bottlenecked on an Owner/Admin. Structural actions (period close, chart edits, trust purge, timekeeper/partner status) stay Owner/Admin-only.
HR Management	`hrManagement`	Team-member HR data: employment fields, compensation, billing rates, payroll banking methods, health/IDV review — all of `hr.*` plus `users.edit_team_profile`.	An HR specialist needs people-data access without other admin powers; reduces who can see salaries/health data.
Compliance Management	`complianceMgmt`	Record a global sanctions-screening override on any payee (any matter or vendor) — the broadest override tier short of Owner/Admin. Mirrors HR Management’s structure (#390).	A dedicated compliance officer can clear AML/sanctions screens firm-wide without being granted full Admin.

3. Accounting actions

Accounting actions fall into three tiers. General = any authenticated staff member; Bookkeeping Management = Owner/Admin or the Bookkeeping add-on; Owner / Admin only = the Bookkeeping add-on is deliberately not enough.

Action	Required access	Why this gate
Apply a client credit to an invoice	General (ungated by design — see below)	Applying an existing client credit balance to that same client’s open invoices only moves money the firm already holds between the client’s own invoices. Nothing leaves the firm and nothing is irreversible, so it is treated as routine collection work.
Issue a credit memo / write-off an invoice	Bookkeeping Management	A write-off reduces revenue / A-R the firm was owed — it is an accounting adjustment, not a routine collection, so it is restricted to bookkeeping-control staff.
Refund a client credit balance	Bookkeeping Management	A refund pays real money out of an operating bank account back to the client. Because cash leaves the firm, it requires bookkeeping-control authority.
Sweep a client credit into trust	Bookkeeping Management	A sweep reclassifies an operating liability into the matter’s trust liability and physically moves cash operating → trust. It touches the trust ledger (By-Law 9), so it is restricted to bookkeeping-control staff.
Transfer operating funds	Bookkeeping Management	Moving money between operating bank accounts is routine bookkeeping control, not structural — so the add-on is sufficient.
Set timekeeper / partner status & nickname	Owner / Admin only	These govern accounting attribution — they auto-create and decommission per-timekeeper / per-partner sub-GLs in the chart of accounts (`4001.NICK` / `4002.NICK` / `3200.NICK`), which is a structural chart change, so the status-setting endpoints are Owner/Admin-only. See §6 Timekeeper, partner & per-timekeeper sub-GLs.
Close an accounting period	Owner / Admin only	Closing a period locks the books for that range (a balanced trial-balance gate must pass first). Locking the ledger is a structural control action, so the Bookkeeping add-on is deliberately not enough.
Reopen a closed period	Owner / Admin only	Reopening unlocks a previously-locked period; same structural-control reasoning as closing.
Post a manual journal entry	Owner / Admin only	Manual journal entries write directly to the GL outside the normal source-document flow, so they sit behind the admin gate.
Edit the chart of accounts	Owner / Admin only	The chart of accounts is the structural backbone of the ledger; renaming or adding accounts changes how every transaction maps.
Purge trust-ledger data	Two different Admins	Deleting trust entries is irreversible and audit-sensitive, so it uses a two-admin rule: the admin who approves a purge must be different from the admin who requested it.

Apply stays ungated — by design

Applying a client credit to an invoice is open to any authenticated staff member, and that is a settled product decision, not a gap.

The rationale (jlevy, #457): the person who should be applying a client’s credit is the Matter Responsible chasing their own collections. Gating Apply behind Bookkeeping Management would force every routine apply-credit-to-invoice through a bookkeeper, creating a bottleneck on day-to-day collections. Keeping it ungated lets the matter-responsible lawyer keep their own collections on time without waiting on Bookkeeping.

It is safe to leave ungated because Apply is fully reversible and never moves money out of the firm — it only reallocates a credit the firm already holds among that same client’s invoices, with a full audit trail. The actions that do move or destroy money (refund, sweep, write-off, purge) remain gated.

Cross-matter scope of Apply

A client credit balance is held at the client (participant) level, not the matter level — it lives as a single 2050 Client Credits liability per client + currency. When you apply it:

The credit can be applied to any open invoice of that client, across all of the client’s matters — it is not restricted to the matter that generated the overpayment.
The matter that was just overpaid is applied first (preferred ordering); remaining credit then flows to the client’s other matters, oldest-due-date first.

By contrast, a sweep into trust is matter-scoped: the target matter must have the same primary client as the credit balance, because trust is held per client-matter.

Why a bookkeeper can apply a credit but not close a period

The dividing line is reversibility and structure:

Apply / refund / sweep / write-off / operating transfer move or adjust money the firm already accounts for. They are routine, individually reversible, and each leaves a full audit trail. (Apply is the most routine of all, hence ungated; the rest sit at the Bookkeeping tier.)
Close period / edit chart of accounts / post manual journals change the shape of the ledger or lock it. They are structural, so they stay Owner / Admin only even for a user who holds the Bookkeeping add-on.
Purge trust data is irreversible and trust-regulated, so it raises the bar further to a two-admin rule.

4. Matter-level access

Two distinct mechanisms govern access within a matter.

Matter Responsible

Matter Responsible is a per-matter Staff Function (alongside Matter Introducing and Matter Assigned), set on the matter’s Staff tab. A user marked Matter Responsible on a matter is elevated for that matter only to perform a small set of otherwise-admin actions:

Elevated for a Matter Responsible	Why
Apply / release a legal hold on the matter	The responsible lawyer owns the matter’s lifecycle.
Manage matter access settings (division, access list, client-portal close policy)	They decide who sees the matter and how the client portal winds down at close.
Sign a Form 9A trust requisition (only if the org enables it)	An org toggle lets the Matter Responsible sign trust disbursements without the global Trust Signer flag — keeping trust authority close to the matter.
Override sanctions screening on the matter’s payees (only if the org enables it)	An org toggle lets the Matter Responsible clear a matter-scoped screening hit; firm-wide overrides still need Compliance Management or Admin.

Outside these elevations, a Matter Responsible has only their base-role permissions — being Responsible does not make someone an Admin.

Matter Planner

Matter Planner is an org-wide feature subscription, not a per-user role. When the org subscribes, the full matter-management surface unlocks for staff: matter participants, loans, approvals, comments, notifications, matter email, folders, documents, disbursements, fees, trust entries, trust transfers, critical dates, time tracking, and client-portal intake. When the subscription is inactive, those routes return a payment required response regardless of role. Manage it under Settings ▸ Billing.

5. Client-portal access tiers

External clients reach their matters through the client portal. Portal access is granted per participant, per matter — never globally — and is controlled by the Matter Responsible, an Admin, or the Owner (the same people who own the matter’s access settings).

A client participant either has portal access or not (has_portal_access), and when they do, their access is a set of independent capability toggles. Each toggle lights up one area of the client’s portal:

Capability	What the client can do
Communications	Use the Discussions / messaging tab to talk with the firm.
Documents	View documents the firm has shared on the matter (still subject to per-folder sharing).
Uploads	Upload files into the matter’s client-uploads area.
Billing	View invoices and billing for the matter.
Approvals	Review and approve approval requests — the highest-trust client capability.

The capabilities map to three legacy tiers for at-a-glance labeling:

Tier	Has	Meaning
Owner	Approvals (top capability)	Can approve on the matter — the most authoritative client.
Billing	Billing, no Approvals	Can see money, can’t approve.
User	Neither	View / communicate / upload only.

A Discussions-only client is simply one granted Communications and nothing else.

Granting, revoking, and matter close

Granting / changing capabilities and changing the portal-close policy require Matter Responsible / Admin / Owner.
Revocation is immediate and forceful. When has_portal_access flips off — a participant is demoted from client to a non-client type, a requisition completes, or the matter closes — all of that user’s portal sessions are revoked and the event is audit-logged as a revocation (not a quiet edit), so security teams can detect it.
Matter close has a grace window. A hard close cuts portal access immediately; a grace close keeps access alive for a configured number of days after close before it expires. The Matter Responsible sets this policy.

5a. Client intake / Requests & the Client Introducer

Before a matter exists, a client can open a request (“Start a new request”) from the client portal — an intake thread that isn’t yet attached to any matter. Two access concepts govern who on staff can see, answer, and convert those requests: the Client Introducer (a global per-client claim) and the intake authority gate that flows from it.

The Client Introducer

The Client Introducer is the global “this client is mine” claim on a client (participant) — the introduced_by field on the participant record, pointing at a single staff user. It is set per client, not per matter, and it follows the client everywhere: it is shown across that client’s portal, and it earns referral credit (the client introducing Attribution basis in §5 of the Fees Attribution report credits whoever introduced the matter’s primary client).

Who can see and reply to intake requests

The intake inbox (Requests) is the Introducer’s to screen — so a rainmaker’s hard-won clients remain their clients. Visibility and reply are gated to:

Owner / Admin / Manager — OR the requesting client’s Client Introducer.

The practical effects:

Staff user	What they see in the intake inbox
Owner / Admin / Manager	Every intake request in the org.
The client’s Introducer (any role, incl. General)	Only the intakes from the clients they introduced.
Any other staff (even with Matter Planner)	Nothing — the request is hidden; a direct fetch returns a 404.

A non-privileged Introducer therefore sees only their own introduced clients’ requests, never anyone else’s. The 404 (rather than 403) is deliberate — it doesn’t reveal that the intake exists. This replaces the prior “any Matter-Planner staffer can see all intake” behavior.

New-request notifications

When a client opens a new request, the platform notifies their Client Introducer in-app and by email (best-effort; the email send is production-guarded), in addition to the existing fan-out to staff who can manage matters. So the Introducer learns about their client’s request directly, even if they’re a General-role user.

Converting an intake into a matter

Converting a request into a matter is gated by the same intake authority as viewing it — Owner / Admin / Manager or the client’s Introducer. On convert, the platform automatically:

Adds the requesting client as a (non-primary) client participant of the target matter, reusing the existing client identity when one matches by email (it never becomes the matter’s primary client — that stays whoever the matter was set up with).
Grants that participant User-tier portal access — the Communications capability only (matter + Discussions). It never grants Billing or Approvals, so the conversation the client started simply follows them onto the new matter.

The convert step is idempotent and non-escalating: if the client is already a participant it only ensures the User-tier (Communications) grant is present, and it never elevates a non-client participant (e.g. a counterparty) — only client-type rows can carry portal access. The User-tier grant here is exactly the lowest client-portal tier described above.

6. Timekeeper, partner & per-timekeeper sub-GLs

The timekeeper and partner designations are how Athenty attributes revenue, fee credit, and equity to individual people in the general ledger. Both are per-user flags managed from Settings ▸ Team ▸ <member> ▸ Accounting, and both are independent — a user can be neither, a timekeeper, a partner, or both. The two flags share one GL nickname so a timekeeper-partner keeps a single handle across all of their sub-GLs.

Who can set timekeeper / partner status

Setting either flag is Owner / Admin only. Enabling a flag auto-creates accounts in the chart of accounts — a structural change — so it sits behind the admin gate rather than the day-to-day Bookkeeping add-on (unlike the routine accounting actions in §3). The endpoints (PATCH /users/:id/timekeeper, PATCH /users/:id/partner) reject any caller who is not Owner or Admin, and every enable/disable is audit-logged.

The GL nickname

Enabling timekeeper or partner status requires a nickname: 1–5 uppercase alphanumeric characters (e.g. JLEVY, JCHEN, MWAT), normalized to uppercase and unique per org, case-insensitive. The nickname is the handle that names every sub-GL the user owns, so it is shared across the timekeeper revenue sub-GLs and the partner equity sub-GL. A nickname already in use by another member — even a former timekeeper whose flag is off — is rejected; pick another (the UI suggests NICK2). Disabling a flag preserves the nickname so a later re-enable re-uses the same sub-GLs.

Per-timekeeper revenue sub-GLs (`4001.NICK` / `4002.NICK`)

When a user is flagged a timekeeper, Athenty auto-provisions two revenue sub-GLs under the standard service-revenue parents:

Sub-GL	Hangs off	Holds
`4001.NICK`	4001 Fixed Fee Revenue	the timekeeper’s fixed-fee dockets (fixed / block / contingency / retainer-as-revenue / other)
`4002.NICK`	4002 Time Revenue / Hourly Fees	the timekeeper’s hourly time entries and hourly fee dockets

Both parents roll up into 4000 Service Revenue. The codes use dot notation (4001.JCHEN, not 4001-JCHEN) to match the convention Canadian bookkeeping software uses, so bookkeepers’ muscle memory carries across. The sub-GLs are system accounts: they cannot be deleted, and disabling timekeeper status decommissions them by flipping them inactive (append-only — past postings stay, the account just stops accepting new entries). Re-enabling reactivates the same rows rather than creating new ones.

Every org also has standing catch-all sub-GLs — 4001.UNASSIGNED and 4002.UNASSIGNED — for fee/time revenue that can’t be tied to a timekeeper.

How fees route to each timekeeper’s sub-GL

Revenue routing happens when an invoice is posted to the GL. Each fee / time line traces back to its work-in-progress source to find the responsible user, then the credit lands on that user’s sub-GL:

A time-entry line → the time entry’s user_id; revenue kind is always hourly → 4002.NICK.
A matter-fee line → the fee’s posting user; the fee’s type decides the kind (hourly → 4002.NICK, everything else → 4001.NICK).
A line whose source user is not a timekeeper, has no nickname, or whose sub-GL is missing/inactive falls back to the matching 4xxx.UNASSIGNED catch-all — the entry always stays balanced.

Routing is forward-only: rows posted before this feature existed remain on the legacy 4000 parent, and the trial balance reconciles as SUM(4001.*) + SUM(4002.*) + legacy 4000. Existing 4000-rooted reports keep working; new postings flow into the children.

The per-timekeeper sub-GLs and the Fees Attribution report answer two different questions from the same fee-credit source resolution:

The sub-GLs are the general-ledger view — where each dollar of revenue physically posts, by timekeeper, for the income statement / trial balance.
Fees Attribution (Accounting ▸ Reports) is the management view — billed vs collected vs written-off fees per person over a period, viewable through five independent Attribution basis values: fee credit (the timekeeper who did the work — the same source resolution the sub-GL routing uses), plus matter responsible / matter assigned / matter introducing (the matter’s Staff Function holders, split by each Staff Function’s credit %), and client introducing (whoever introduced the matter’s primary client). Each report is a single Attribution basis, so a dollar is never double-counted across bases.

A staff member doesn’t have to be a timekeeper to be attributed a fee — the Staff-Function bases credit the matter’s Staff Function holders regardless of timekeeper status. Being a timekeeper is specifically what gives a person their own revenue sub-GL and a fee-credit row in the GL.

Per-partner equity sub-GLs (`3200.NICK`) and profit share

Flagging a user a partner auto-provisions a single capital account 3200.NICK under the 3200 Partner Equity parent (same dot notation, same shared nickname). All of that partner’s activity posts to that one account, and the equity statement reconstructs the components from each journal entry’s type:

Activity	Posting
Capital contribution	Dr operating bank / Cr `3200.NICK`
Partner draw	Dr `3200.NICK` / Cr operating bank
Period-end profit share	Dr `3000 Retained Earnings` / Cr `3200.NICK`

A partner also carries an optional profit-share % (0–100). At period end, the profit-allocation run reads net income from the income statement and credits each partner’s 3200.NICK by their share (a loss flips the entries). Draws, contributions, and profit allocations are accounting actions in their own right; this section only covers who can grant partner status and how the sub-GLs are named — the day-to-day mechanics live on the Accounting pages.

Settings ▸ Access Levels — manage base roles + the HR / Bookkeeping / Compliance add-ons
Settings ▸ Accounting period close — closing and reopening periods
Accounting ▸ Invoices — client credit, overpayments, write-offs, refunds
Accounting ▸ Trust operations — sweep-to-trust and trust-ledger handling
Settings ▸ Audit Log — every gated action is audit-logged