Access Scopes

Access scopes are the authorization boundaries that partition a Tagnet deployment's data. In a single-site deployment they are invisible: everything lives in one place and there is nothing to configure. In a multi-site deployment, an access scope usually represents a physical site (a warehouse, a plant, a service territory) or, less commonly, a department or region. Resources such as devices, inventory, and locations belong to exactly one scope, and users are assigned to the scopes they need to see and manage.

This guide covers the Access Scopes page: how the system scope and site scopes differ, how to create and edit scopes, how the scope Code works, and how definitions like your item catalog can be shared or site-specific. For how users are assigned to scopes and how roles interact with them, see Users, Roles & Access Scopes. For how the header filter narrows what you see across sites, see Scope Filter.

The System Scope and Site Scopes

Every Tagnet deployment has exactly one system scope, seeded as "System" (installations set up before that change may still call it "Global"). Alongside it, you create one site scope per physical location, department, or region that needs its own data boundary.

	System scope	Site scopes
How many	Exactly one, always present	One per site, department, or region you create
Identity	A globe icon and a fixed System badge	Your own name and optional Label (e.g., "Site," "Region"), shown on a teal chip with a shield icon
Read access	Every user can see it	Only assigned users
Write access	Only users explicitly assigned to it	Only assigned users
Can be deleted	No	Yes
Holds	Shared definitions (catalog items, types, custom fields, sequence generators, workflows) and, until you create a site scope, everything else	Shared definitions (if your Scoping policy allows it) plus all operational records: devices, device groups, inventory, and locations

The system scope is where a fresh Tagnet installation starts: your item types, catalog, and (until you provision a site) even your inventory and devices all default there. As soon as you create a site scope, the picture usually flips: your operational data belongs to sites, and the system scope becomes the place shared reference data lives.

Note: Throughout Tagnet, the system scope is identified by a globe icon and blue coloring, wherever it appears: in scope chips, the Access Scopes list, the scope filter, and dropdowns. Every other scope (a site, department, or group) appears in teal with the shield icon, the same in lists, record headers, and pickers.

Shared Definitions vs. Site-Only Records

Not everything a scope can hold behaves the same way:

• Shared definitions describe or configure how your system works: catalog items, item types, location types, device types, transaction types, custom fields, sequence generators, and workflows. These may live in the system scope (shared across every site) or in a specific site scope (visible and editable only within that site), depending on how your organization wants to manage its catalog.
• Operational records are things that physically exist or happened: inventory items, devices, device groups, locations, floor plans, pending tag mappings, and commission batches. These live in a site scope, never the shared system scope, since "which site is this device or item actually at" should always have an answer. This is enforced everywhere they are created, in the app and through the API: the scope picker only ever offers site scopes, and a request to create one in the system scope is refused with a message explaining that operational data needs a site.

First-run setup creates your first site, so there is always somewhere to put them. If an installation has no active site scope at all (one set up before this rule, or whose only site was deactivated), the create pages show a Create a site scope first notice in place of the scope picker, and nothing is created until a site exists.

Whether shared definitions like catalog items and item types can also be owned by an individual site is controlled by the Scoping policy, covered below.

The Access Scopes Page

Open the Access Scopes tab of the Users page to see every scope in your deployment: name, Code, Label (or the System badge), and how many users are assigned. Requires the Admin role.

Click a row to open its detail page, which has two tabs:

• Overview: name, Code, Label, description, and audit history (who created and last updated the scope). Three hero cards at the top show user, inventory, and device counts, each linking to a pre-filtered list: View inventory and View devices jump to the Inventory and Devices pages already filtered to this scope, and Manage users jumps to the Users tab.
• Users: everyone currently assigned to this scope, with a search box to add more. This replaces the old "Manage Users" dialog: assigning users to a scope is now part of the scope's own page rather than a separate popup.

Records left in the system scope

Installations set up before Tagnet enforced this rule may still have devices, locations or inventory in the system scope. When they do, the Access Scopes page shows a warning with the counts and a Move to a site button. Everything moves together to the site you choose, in one step: location hierarchies, group membership, tag assignments, floor plans and transaction history all stay intact, and the site's Inventory, Devices and Locations pages show the records afterwards. The move is recorded in Security Events.

Until you move them, the records stay visible and usable where they are. Only new placement in the system scope is refused.

Creating a Scope

1. Open the Access Scopes tab of the Users page and choose Access Scope from the Add menu.
2. Enter a Name (e.g., "Chicago Warehouse"). The Code field fills in automatically as a slugified version of the name.
3. Override the Code if you want something different (e.g., chi-wh instead of chicago-warehouse).
4. Optionally add a Label (a category like "Site" or "Region") and a Description.
5. Click Create. A confirmation dialog shows the exact Code the scope will be created with and explains that external systems use it, and that changing it later breaks any integration still configured with the old value. Click Create scope to confirm.

Editing a Scope

Open a scope's detail page and click Edit. What you can change depends on whether it's a site scope or the system scope:

Field	Site scopes	System scope
Name	Editable	Editable, renaming is safe: the system scope is identified internally, not by name, so this is how you brand it as your organization (e.g., rename it to "Acme Co")
Label	Editable	Fixed to System; the field doesn't appear on the form
Description	Editable	Editable
Code	Editable, with a warning (see below)	Editable, with an elevated warning (see below)

Tip: Renaming the system scope to your organization's name is a normal, supported thing to do. Its special behavior (implicit read for everyone, write requires assignment, cannot be deleted or deactivated) is tied to an internal flag, not to its name.

Changing a Scope's Code

The Code is the stable, URL-safe identifier external systems use to reference a scope (for example, an integration calling ?scope=east-site). Unlike some other identifiers in Tagnet, a scope Code is not permanent: you can change it after creation, but doing so has a real consequence.

Format rules:

• Lowercase letters, digits, and single hyphens only (e.g., chicago-warehouse, site-a, mfg01)
• No leading, trailing, or consecutive hyphens
• Maximum 100 characters
• system and global are reserved and cannot be claimed by a site scope (the system scope itself may use or return to them). New installations seed the system scope with code system; older ones may still hold global

Why changing it matters: every other place in Tagnet that references a scope stores the numeric ID internally and only looks up the Code for display, so a rename never breaks anything inside Tagnet. The risk is entirely external: API clients and integrations configured with the old Code stop resolving the scope. Tagnet's scope-by-code API deliberately returns the same result whether a code doesn't exist or the caller simply lacks access to it (so a client cannot probe for scopes it isn't allowed to see), which means a stale integration fails silently rather than with a clear "not found" error. There's no way to tell from the API response alone that the code was renamed rather than revoked.

Because of this, changing a Code always shows a confirmation dialog naming the consequence before it takes effect:

• For a site scope, the dialog explains that any client configured with the old code will stop resolving the scope, and that the failure is silent on the API side.
• For the system scope, the warning is elevated: this code is the handle every integration that reads shared data uses, so the blast radius is organization-wide, not site-only.

Every Code change, old value and new value, is written to the security audit trail as a configuration change. See Security Events.

Important: Retired codes can be claimed by a different scope later, which would silently reroute a stale integration to the wrong data. Don't reuse a retired Code; pick something new.

Sharing Your Catalog Across Sites: the Scoping Policy

By default, catalog items, item types, location types, device types, transaction types, custom fields, and sequence generators are all created in the system scope, shared by every site with no prompt. For many multi-site deployments this is exactly right: one catalog, used everywhere.

If your organization needs individual sites to maintain their own catalog entries alongside the shared ones (for example, a site-specific consumable that only one plant stocks), an administrator can enable the Scoping > Site Catalog policy on the Policies page. Once enabled:

• Definition create/edit forms show an Availability choice instead of a plain scope field: "Shared across {your organization}" (the default) or "{Site} only."
• The Items page gains an Availability filter (All / Shared / a specific site) so you can narrow the catalog to what a given site owns.
• List pages for shared definitions (Items, Types, Custom Fields, Sequence Generators) never hide system-scoped rows when you filter the header site filter down to specific sites: a shared item type stays visible no matter which sites you're focused on, because it's still usable everywhere.

Turning the policy off later does not touch any site-scoped definitions you already created; it only hides the Availability choice going forward, and new definitions resume routing to the shared scope silently.

Visual Conventions

Tagnet uses consistent icons and colors for scope identity across the app:

Indicator	Meaning
Globe icon, blue	The system scope (identity, not protection)
Shield icon, teal	Any other scope: a site, department, or group
Outlined blue System chip with a lock	A built-in record, such as the seeded alert routing rule or notification group, that cannot be deleted. It is not a scope
Small gray lock icon on a row	You can view this row but cannot edit it, typically a shared resource outside your write access

Deleting a Scope

Deleting a scope permanently removes it and everything in it: items, inventory, locations, devices, workflows, and every other record scoped to it. Open a scope's actions menu and choose Delete. Tagnet shows an estimate of what will be deleted before you confirm, and you must type the scope's name to proceed. Because deletion of a large scope can take a while, it runs as a background task with progress shown in the dialog.

The system scope cannot be deleted; the action is disabled in its menu. The only active site scope cannot be deleted or deactivated either: operational records always need a site to live in, so create another site first.

Important: There is no undo. If you want to keep a scope's history but stop using it day to day, don't delete it, just stop assigning users and devices to it going forward.

Permissions

Managing access scopes (create, edit, delete, assign users) requires the Admin role. All users can read the system scope's shared definitions regardless of role; site scope data is visible only to users assigned to that scope.

FAQ

Q: We renamed the system scope to our company name. Did that break anything? A: No. The system scope's special behavior (shared read access, write requires assignment, can't be deleted) is tied to an internal flag, not to the name or the Code. Existing data, references, and integrations that use scope IDs are unaffected. Only an integration that hardcoded the old Code in a ?scope= parameter would need updating, and only if you also changed the Code.

Q: I changed a scope's Code and now an integration is failing. How do I tell if that's why? A: Check the Security Events log for an AccessScopeCodeChanged entry; it records the old and new Code together with who made the change and when. Tagnet's API intentionally can't distinguish "code doesn't exist" from "no access" in its response, so the failure on the integration side won't say "code was renamed," it will just look like the scope stopped resolving.

Q: Can I move a device or an item type from the system scope into a site, or the other way around? A: Yes, edit the record and change its Access Scope (or Availability, for definitions when the Scoping policy is enabled). Operational records like devices can only move between site scopes, or from the system scope into a site, never the other direction once a site scope exists.

Q: Why can't I put a new device in the system scope? A: Operational data (devices, device groups, inventory, locations) is meant to live in a site scope, not the shared system scope, once your deployment has at least one site scope: "where is this device" or "where is this stock" should always have an answer. For devices and device groups this is enforced directly, which is why the scope picker on the device form only lists site scopes. Inventory and locations are steered toward site scopes the same way but aren't hard-blocked from the system scope yet.

Q: What happened to the "Manage Users" dialog? A: It moved. Assigning users to a scope is now the Users tab on that scope's own detail page, alongside an Overview tab with the scope's details and quick links to its inventory and devices.