Roles and access

Who can do what in Tagaris. There are two kinds of authority: install-wide, held by the install owner, and per-organisation, held by that organisation's admins.

The roles

Role	Scope	What it can do
SuperAdmin	the install	Everything below, plus Application settings (licence, single sign-on, organisations and cross-org groups) and any organisation.
Admin	one organisation	Manage that organisation: its users and their roles, its settings, and all its data.
Editor	one organisation	Add and change register data (assets, stock, people, locations and so on), work issues, and work on vendors, contracts and purchase orders. Cannot place or cancel a purchase order, and cannot manage users or settings.
View only	one organisation	Look and search. Changes nothing, and that includes reporting an issue, running a report or exporting. Free, and unlimited.

Admin, Editor and View only are per-organisation. A person can hold a different role in each organisation they belong to. (In the single sign-on mapping and the API the View only role is written VIEWER.)

Most people do not fit three roles. Someone in HR needs to take kit back from a leaver and nothing else; someone in Finance signs off orders and never edits an asset. That is what access groups are for.

Access groups

An access group is a set of permissions with a name. It adds to a person's role and never takes anything away. Give a view-only person an HR group and they can do that one job; they still cannot edit an asset.

Administrators manage them under Settings, Organisation, Access groups:

1. Add a group: a name, what it is for, and tick the permissions it gives.
2. Open the group and tick who is in it. Or use the users list (Settings, Users), which has a tick box per group against each person, and tick groups on an invite so a new person starts with them.
3. A person can be in several groups and has all of their permissions.

They work with or without single sign-on. With it, a directory group can be mapped onto an access group, so membership follows your directory (see below).

Some worked examples:

Group	Role to give	Permissions to tick
HR, leavers and starters	View only	Assign, check out, check in and move assets. Check out, install and issue stock.
Finance	View only	Place and cancel purchase orders. Run reports and export data.
Service desk	View only	Report issues and add notes. Triage and resolve issues. Assign, check out, check in and move assets.
Purchasing lead	Editor	Place and cancel purchase orders (the one thing an Editor lacks).
Auditor	View only	Record physical audits.

The permissions

Area	Permission	What it covers
Assets	Add and edit assets	Details, status, photos, attachments, maintenance records and imports.
Assets	Assign, check out, check in and move assets	Who has it and where it is, including putting it back into stock. Also lets someone change its status.
Assets	Record physical audits	Stock-take and marking an asset as audited, in the browser and the mobile app.
Assets	Dispose of and delete assets	End of life, reinstating, and deleting a data entry mistake.
Stock	Add and edit stock items	Accessories, components and consumables, and their quantities.
Stock	Check out, install and issue stock	Hand an accessory to a person, fit a component, issue a consumable, and take them back.
Register	Manage people, locations, categories, templates and software	The lists the assets refer to.
Issues	Report issues and add notes	People with no sign-in at all use the staff form instead.
Issues	Triage and resolve issues	Status, priority, category, assignee, linking an asset and resolving.
Purchasing	Work on vendors, contracts and purchase orders	Add and edit them, attach documents, and receive deliveries.
Purchasing	Place and cancel purchase orders	Mark as ordered, cancel, reopen and delete orders; delete contracts; merge and delete vendors.
Reports	Run reports and export data	The Reports page, the report builder, and CSV or JSON exports of the register.

Twelve permissions in all. An Editor has all of these except "Place and cancel purchase orders". An Admin has all of them. Managing users, settings, access groups and the licence belongs to the Admin role and the install owner, and no access group can give it.

The same rule applies everywhere: the browser, the mobile app and personal API keys. A personal API key can do what its owner may do, and no more.

Sites: limiting what a person sees

A person can be limited to particular sites. On the users list, the Sites column against each person opens a list of the organisation's locations; tick the ones they may see, and each covers everything under it (a site covers its floors, rooms and racks). Nothing ticked means the whole organisation. Administrators always see everything.

The rule is simple: a site limit hides what is placed at another site. Assets placed at other sites, and those sites themselves, are gone from the lists, the pages, the search, the dashboard, reports and exports, the mobile app and a personal API key. An asset placed nowhere (in stock, or with a person) belongs to no site, so everyone sees it. Stock items, people, vendors, contracts and orders have no site and are not limited. A site-limited person can only place an asset at one of their sites.

Seats

A seat is used by anyone who can change something: an Admin, an Editor, or a view-only person who has been given a permission through an access group (including "Run reports and export data"). View-only people who can only look use no seat, so a whole company can have a view-only sign-in on any plan.

The install owner is not a seat and is not counted as a user. That is the account the setup wizard made: the SuperAdmin, a local password login that stays as the break-glass however you sign in day to day, with full access everywhere. So the free plan is the owner plus any number of view-only people, and a five seat plan is the owner plus five people who change things. Setting up single sign-on changes none of this: sign in through it or with the owner's password, and only the other people who change things use seats.

When a licence lapses, the organisation returns to the free plan: the seat holders are paused until it is renewed. The owner and the view-only people carry on.

SuperAdmin: the install owner

SuperAdmin is the person who owns the installation. It is set on the first-run setup account and is separate from the per-organisation roles. A SuperAdmin:

• Manages Application settings: the Tagaris licence, single sign-on, organisations, and cross-org groups. These are install-wide, so an ordinary organisation Admin does not see them.
• Can act in any organisation, with full Admin authority there.
• Is a local (password) login. This is deliberate: it is the break-glass account, so recovery never depends on single sign-on.

Keep SuperAdmins few, and protect their passwords. There is always at least one (the setup owner). On an upgrade that introduces this role, the earliest existing account is promoted so system settings stay reachable.

Application settings vs organisation settings

Settings are split into Organisation (any Admin) and Application (SuperAdmin only):

• Organisation: general, email, alerts, branding, users, access groups, integrations, data.
• Application: licence, single sign-on, organisations, cross-org groups, security, API, backups, access overview.

The split is enforced on the server, not merely hidden in the interface. The licence, single sign-on and add-organisation actions all require SuperAdmin.

Single sign-on and roles

When single sign-on is set up, each user's role comes from your directory through a required mapping: Entra App Roles, Okta or Authentik groups, Keycloak roles, or whatever claim your provider sends, to Tagaris roles. Anyone without a mapped value gets the default role (View only or Editor, never Admin).

The same mapping can point a directory group at an access group, by name:

Tagaris.Admin   = ADMIN
IT-Staff        = EDITOR
Finance-Team    = Finance
HR-Team         = HR leavers
IT-Staff        = Purchasing lead

A value can appear on more than one line, so one directory group can give a role and an access group. The access groups must exist first, or saving is refused with the names it could not find. Group membership from the directory is re-checked at every sign-in: leave the directory group and the access group goes at the next sign-in. A group an administrator gave by hand is never removed by a sign-in. Google Workspace is the exception: its tokens carry no groups, so everyone from your domain gets the default role and an administrator promotes people by hand. Single sign-on can grant up to Admin, never SuperAdmin: SuperAdmin is the local install owner, set up in Tagaris, not in your directory. See Single sign-on for the setup steps.

Requiring single sign-on

With "Require single sign-on" on, password sign-in is blocked for everyone except SuperAdmins. Everyone else must use single sign-on. The SuperAdmin's local password login stays available as the break-glass account.

If single sign-on breaks

Sign in as the SuperAdmin with their password (the "Sign in as owner" link on the login screen), then fix or turn off single sign-on. If every SuperAdmin password is also lost, recovery is out of band through server access to the database; there is no standing recovery account beyond the owner.

Cross-org groups

Groups are part of the multiple organisations add-on. For people who need the same access across several organisations, a SuperAdmin can create a cross-org group: a name, one role, and the organisations it covers. Add people to the group and they get that role in all of those organisations, without setting each one up by hand.

A person's effective role in an organisation is the higher of their direct role there and any group that covers it. A cross-org group can also carry permissions, the same ones an access group has, applied in every organisation it covers, so an MSP's service desk group can work issues and move kit across every client without being Editors anywhere. So a group never takes access away; it only adds or raises it. A group above view only, or with a permission, uses a seat in each organisation it covers. They are managed under Settings, then Application, then Cross-org groups.

A cross-org group gives a role across organisations. An access group gives particular permissions inside one organisation. They are separate, and a person can have both.

For developers

• What a person may DO is canDo(permission) in src/lib/rbac.ts, backed by the pure catalogue in src/lib/org-permissions.ts (role permissions plus access groups). Every action names the permission it needs; a unit test fails the build if one guards on the blunt canWrite() or compares a role to VIEWER or EDITOR.
• Admin-only and install-wide checks are can(context, capability) in src/lib/permissions.ts, where context is { superAdmin, role }. Every gate should go through it rather than comparing roles inline. system.* capabilities need SuperAdmin; org.* and data.* are ranked by role (ADMIN > EDITOR > VIEWER).
• getActiveContext() (src/lib/session.ts) resolves the active organisation, the user's effective role there, the superAdmin flag, and the list of organisations they can reach. canActive(capability) is the convenience wrapper.
• Effective role folds direct memberships and cross-org groups with mergeOrgAccess (src/lib/access.ts, highest role per organisation).
• Data model: User.isSuperAdmin, Membership (per-org role), AccessGroup / AccessGroupMember (per-org permissions, source is manual or sso), and Group / GroupOrg / GroupMember (cross-org groups).
• Single sign-on enforcement is a better-auth before-hook in src/lib/auth.ts that blocks /sign-in/email for non-SuperAdmins when isSsoRequired() is true.