Users, Roles & Access Scopes

This guide explains how Tagnet controls who can access the system and what they can do. Tagnet uses a combination of user accounts, roles, and access scopes to provide flexible, secure access control.

Overview

Tagnet's access control model has three layers:

Layer	What It Controls	Example
User Account	Who can log in	jane.doe@company.com
Role	What actions they can perform	Can create readers, edit inventory
Access Scope	What data they can see	Chicago Warehouse data only

Think of it this way:

• Your user account gets you in the door
• Your role determines what buttons and features you can use
• Your access scope determines which data appears on your screen

User Accounts

Each person who uses Tagnet has their own user account with a unique email address and password.

Account Status

Accounts can be in the following states:

Status	What it means
Active	User can sign in and access the system.
Inactive	User cannot sign in. Used when someone leaves or takes extended leave. History is preserved for audit purposes.
Locked	User has exceeded the failed sign-in threshold and Identity has temporarily locked the account. The Locked chip appears next to the Active/Inactive chip on the user row. An admin can unlock the account immediately. See Unlocking a Locked Account below.

Deactivating an account preserves the user's history for audit purposes while preventing access. Deactivation and lockout are independent: a user can be both inactive and locked.

First Login

When your account is created, you will receive an invitation link from your administrator, either by email (when email is configured) or as a link shared directly. Clicking the link takes you to a page where you set your own password and complete account creation. On first login, verify your account details are correct.

If you do not receive the invitation link or it has expired, contact your administrator to resend it or create a new one.

Roles

Roles define what a user can do in Tagnet. Each user is assigned one role.

The Roles tab of the Users page shows the full permission chart: every permission down the side, grouped by area and with its description, and one column per role with a check where that role grants it. Hover a role's heading for its description; the count under each role is how many users hold it. Roles are system-defined and cannot be edited.

Available Roles

Role	Description	Typical Use
Admin	Full system access	IT administrators, system owners
Contributor	Manage readers, inventory, and configuration	Site managers, team leads
Operator	Day-to-day operations	Warehouse staff, technicians
ReadOnly	View data without making changes	Auditors, reporting users
ApiClient	Read-only API access	Dashboards, reporting integrations
ApiInventory	API access that adds inventory against the existing catalog	Print and production stations, commissioning
ApiIntegration	Read/write API access	ERP systems, external integrations

Role Capabilities

Admin

• Everything below, plus:
• Create and manage user accounts
• Assign roles and access scopes
• Configure system settings
• View audit logs
• Create, edit, reorder, and delete workflows and message templates (the Manage Workflows permission, which for the beta only the Admin role has)
• View integration activity, such as the Commissioning Log (the View Integrations permission, which only the Admin role has)

Contributor

• Everything below, plus:
• Create, edit, and delete readers
• Deploy reader configurations
• Send tag reads and telemetry through the ingest API for readers in their access scopes (the Ingest Reads permission)
• Manage inventory items
• Create and edit locations
• Define item types and custom fields
• Export reports
• View workflows, their run order and their runs, and message templates; create and edit movement rules. Creating and editing workflows and templates is an Admin task for the beta

Operator

• View all readers and their status
• View and edit inventory items
• View locations and item definitions
• Run and view reports
• Receive and manage their own notifications (notifications require no specific permission and are available to every role)
• Cannot access Scan Events or Workflows, including Workflow Executions, Message Templates, and Movement Rules; those pages are hidden. Assign Contributor to a user who needs to view automation, or Admin to one who manages workflows

ReadOnly

• View readers, inventory, locations
• View reports
• Cannot make any changes

ApiClient

• Access the API for system integration
• Read-only access to readers, inventory, locations
• Ideal for dashboards and reporting integrations
• Cannot make changes to data

ApiInventory

• Everything ApiClient can read
• Commission tags, map tags to instances, add and update inventory, and record movements
• Uses the items, locations, and types that already exist; cannot create or change them
• Send tag reads and telemetry through the ingest API for readers in its access scopes, for example from a handheld or a gateway
• Ideal for a print or production station that creates inventory against a catalog someone else maintains
• Cannot manage devices, users, roles, or settings

ApiIntegration

• Full API access for system integration
• Read and write inventory, locations, readers
• Send tag reads and telemetry through the ingest API for readers in its access scopes
• Create and update item definitions
• Create, edit, and delete item types, location types, and device types
• Create, edit, and delete custom fields
• Ideal for ERP systems and two-way integrations that need to provision the full data hierarchy
• Cannot manage users or system settings

Which Role Do I Need?

If you need to...	You need at least...
View inventory and reports	ReadOnly
Update inventory status and locations	Operator
Add new readers or create item definitions	Contributor
Create or change workflows and message templates	Admin
Create user accounts or change system settings	Admin
Pull data into a dashboard (API)	ApiClient
Commission tags or add inventory from a station, without touching the catalog (API)	ApiInventory
Push updates from an ERP system (API)	ApiIntegration
Send tag reads from a handheld, gateway, or custom reader integration (API)	ApiInventory

Access Scopes

Access scopes control which data you can see. This is especially useful for organizations with multiple sites, departments, or regions. This section is a quick overview from the user-and-role side; for the full guide to scope management, the system scope, scope Codes, and shared vs. site-specific catalog data, see Access Scopes.

How Scopes Work

An access scope is a container for data. Resources like devices, inventory items, and locations belong to a scope. Users are assigned to one or more scopes and can only see data within those scopes.

Example Organization:

Access Scopes:
├── (system scope: shared resources)
├── Chicago Warehouse
├── Dallas Distribution Center
└── Phoenix Manufacturing

Users:
├── admin@company.com      → Admin (sees everything)
├── chi.manager@company.com → Contributor, assigned to Chicago
├── dal.operator@company.com → Operator, assigned to Dallas
└── regional@company.com    → Contributor, assigned to Chicago + Dallas

In this example:

• The admin sees all data across all sites
• The Chicago manager sees only Chicago data
• The Dallas operator sees only Dallas data
• The regional user sees both Chicago and Dallas data

The System Scope

Every Tagnet installation includes exactly one system scope, seeded as "System" (installations set up earlier may still call it "Global") and shown with a globe icon and a fixed System badge. It holds shared resources such as item types, location types, and your shared product catalog.

• All users can see the system scope's resources (read access)
• Only users explicitly assigned to it can create or modify its resources
• Administrators can rename it to your organization's name; its special behavior doesn't depend on the name

See Access Scopes for the full explanation of the system scope, site scopes, and which kinds of data can be shared versus site-only.

Single-Site Deployments

If your organization has only one location, you'll typically have:

• The system scope for shared configuration (item types, templates)
• One site scope (e.g., "Main Warehouse") for your actual data

The system automatically simplifies the interface for single-scope users. See Simplified Interface for Single-Scope Users below.

Multi-Site Deployments

For organizations with multiple locations:

Scenario	Scope Setup
Independent sites	Each site has its own scope; users assigned to their site only
Regional oversight	Regional managers assigned to multiple site scopes
Shared catalog	Common item definitions in the system scope; site-specific items in each site's scope, if your Scoping policy allows it

Scope Filter Dropdown

Users who can see more than one active site scope see a scope filter dropdown in the application header. This lets you narrow which sites' data you see at any given time without changing your actual permissions. The system scope is never one of the filterable options; it's always visible for its shared resources.

For full details on using the scope filter, see Scope Filter.

Simplified Interface for Single-Scope Users

Tagnet automatically streamlines the interface for users who only have access to one scope. This makes the system feel simpler and more personal, like it's "their" system rather than a shared multi-tenant platform.

What changes for single-scope users:

UI Element	Multi-Scope Users	Single-Scope Users
Scope filter dropdown (header)	Visible	Hidden
Scope column in data lists	Visible	Hidden
Scope field in edit dialogs	Visible	Hidden or pre-selected
Scope in user menu	Not shown	Shown with label

Who sees the full scope interface: anyone, administrators included, who can see more than one active site scope. In a single-site deployment nobody sees the scope filter, not even Admins, because there is only one site to filter between.

Who sees the simplified interface:

• Users assigned to one site scope (or none): scope controls are hidden; they see their site's data plus read-only access to the system scope's shared resources

Example: A warehouse operator assigned only to "Chicago Warehouse" will:

• See inventory, devices, and locations from Chicago
• See shared item definitions from the system scope (read-only)
• Not see any scope columns, dropdowns, or filters
• Experience Tagnet as a single-site system

Your scope in the user menu: Single-scope users can always see which scope they're working in by clicking their profile icon in the top-right corner. The user menu displays your scope with its label, for example, "Region: Chicago Warehouse" or "Department: Shipping". This provides a quick reference without cluttering the main interface.

Read-only indicators: When a single-scope user views a shared resource from the system scope (like a standard item definition), they'll see a lock icon indicating it's managed by administrators. They can view it but cannot modify it.

Common Scenarios

Scenario 1: Small Single-Site Operation

Setup:

• 1 Admin user
• 2-3 Contributors (managers)
• 5-10 Operators (warehouse staff)
• All users assigned to "Main Warehouse" scope

Experience:

• Everyone sees the same data
• Roles control who can make changes
• No scope picker in the UI (single scope)

Scenario 2: Multi-Site with Isolation

Setup:

• Central IT Admin (sees all sites)
• Site managers (Contributor, assigned to their site only)
• Site operators (Operator, assigned to their site only)

Experience:

• Site users see only their site's data
• Admin can view and manage all sites
• Sites cannot see each other's inventory or readers

Scenario 3: Regional Management

Setup:

• Regional managers assigned to multiple sites
• Site operators assigned to single site
• Shared item catalog in the system scope

Experience:

• Regional managers have a scope picker to switch between sites
• Can run reports across their assigned sites
• Operators see only their local site

Managing Users (Admin Only)

The Users page has Users and Invitations tabs, both deep-linkable (?tab=users or ?tab=invitations) so you can bookmark or share a link to either one. The Users list can be filtered by Role, and inactive users are hidden by default; toggle Show inactive users in the filter bar to include them.

Viewing a User's Details

Click a user's row (or choose Details from the row actions menu) to open that user's own page at a stable, shareable URL. It has two tabs:

• Overview: identity, status, last login, assigned role, and access scopes.
• Security: an append-only audit trail of every Security Event where this user is the actor, for example their sign-ins, password changes, and any admin action performed against their account. Click any row to open that event's own detail page.

The page header's Actions menu carries the same actions available from the Users list row menu: Edit, Reset Password, Unlock (when locked out), and Deactivate/Activate.

Creating a User

Users are added by sending them an invitation. Invitations require an email address. The new account is locked to that address and only that address can accept the link.

1. Navigate to the Users page.
2. Choose Invite User from the Add menu in the page header, which opens the invite page.
3. Enter the recipient's email address.
4. Choose a role by clicking its card. Each card shows what the role Reads and what it Changes, so you can compare them before you pick.
5. Optionally assign one or more access scopes.
6. Choose an expiry (24 hours, 7 days, or 30 days).
7. Click Create & Send Invitation (when email is configured) or Create Invitation Link (when email is not configured).

After creation, the page itself changes to show the dispatch outcome:

Outcome	What it means
Invitation email sent	The link was queued for delivery. Delivery may take a few moments. Check Email Delivery if the recipient reports not receiving it.
Email not configured	No mail provider is active. Copy the link from the page and deliver it to the recipient manually. Configure a provider in Email Settings to enable automatic delivery going forward.
Email could not be queued	The invitation was created but dispatch failed. Copy the link from the page and share it manually. Use Resend Email from the Invitations tab once the underlying issue is resolved.

The invitation link is shown once after creation, on this page rather than a dialog you could accidentally dismiss. Copy it immediately if you need a manual backup.

Note: If email is not configured, the Users page shows a warning banner. Navigate to Email Settings to configure a provider.

Resending an invitation

If an invitation expires or the recipient didn't receive the original email, you can resend it from the Invitations tab:

1. Find the pending invitation in the Invitations tab.
2. Click the row actions menu and choose Resend Email.
3. Confirm the dialog. Resending issues a new token, so any previously shared link stops working.

Resend is only available when the invitation is still pending and has an email address recorded. If the invitation has expired, revoke it and create a fresh one.

Resetting a User's Password

There are four password-change paths in Tagnet, each recorded differently in the security audit log:

Path	Who initiates it	Audit event
Self-service change password	The user, in-app via their profile	UserPasswordChanged
Self-service forgot password	The user, via the Forgot Password link on the login page	UserPasswordResetRequested then UserPasswordResetCompleted
Admin reset from the Users page	An Admin, in-app	UserPasswordResetByAdmin
Recover Account (Admin Console)	A local server admin, out-of-band	UserPasswordReset

Routine admin reset: Find the user on the Users page, click the row actions menu, and choose Reset Password. Enter a new password and click Save. The user is forced to change it on their next sign-in. A UserPasswordResetByAdmin event is written to the Security Events log with you as the actor. When email is configured, the user also receives a notification email confirming the reset.

Self-service forgot password: Users who cannot sign in can click Forgot password? on the login page, enter their email, and receive a reset link by email. The link is valid for one hour and can only be used once. This flow requires email to be configured. See Email Settings. Account enumeration is mitigated: the page always shows the same acknowledgement message regardless of whether the email matches an account, so you cannot use it to probe whether an address is registered.

All-admins-locked-out: If no Admin-role user can sign in, a Tagnet server administrator can use the Recover Account page in the Tagnet Admin Console on the server itself. That path is for the all-admins-locked-out case only. For routine resets, use the in-app action above.

Unlocking a Locked Account

If a user exceeds the failed sign-in threshold, ASP.NET Core Identity locks their account automatically. On the Users page, a yellow Locked chip appears next to their Active/Inactive status chip.

To unlock the account immediately:

1. Navigate to the Users page.
2. Find the locked user (look for the Locked chip in the Status column).
3. Click the row actions menu and choose Unlock Account. This item is only visible when the account is locked.
4. The lock is cleared and the user can attempt to sign in again.

Unlocking records a UserAccountUnlocked event in the Security Events log with you as the actor.

Note: Accounts also unlock automatically when the lockout window expires. Natural expiry does not emit an audit event. Only admin-initiated unlocks do.

If every Admin-role user is locked out and nobody can reach the Users page, use the Recover Account page in the Tagnet Admin Console on the server. That flow clears the lockout as part of the password reset.

Changing a User's Role

Role and access scopes are both set on the same edit page, reached via Edit from either the user's row actions menu or the Actions menu on the user's own detail page.

1. Navigate to the Users page
2. Find the user and choose Edit
3. In the Role section, click the new role's card
4. Click Update

The change takes effect in the user's active session without requiring a logout. It applies on their next navigation within the app, or within about two minutes if they are idle. There is no need to ask the user to log out and back in.

Assigning Access Scopes

1. Navigate to the Users page
2. Find the user and choose Edit (the same edit page used for role changes above)
3. In the Access scopes section, add or remove scope assignments
4. Click Update

Like role changes, scope assignment changes apply to the user's active session automatically: on their next navigation or within about two minutes. The scope filter dropdown and any scope-restricted data update in place without a re-login.

Deactivating a User

When someone leaves or no longer needs access:

1. Navigate to the Users page.
2. Find the user and click the row actions menu.
3. Choose Deactivate.

Deactivation takes effect immediately. The user's current session is terminated on their next request. They cannot continue using the app or the API, and their existing refresh tokens are revoked. Their history is preserved for audit purposes. A UserDeactivated event is written to the Security Events log. To restore access later, use the Activate action in the same menu.

Managing Access Scopes (Admin Only)

Creating, editing, and deleting scopes, along with the full explanation of the scope Code and how to change it, is covered in the Access Scopes guide. A quick summary:

• Open the Access Scopes tab of the Users page to create a scope, view its details, and assign users. Assigning users happens on the scope's own Users tab rather than a separate dialog.
• Every scope has a Code, a short URL-safe identifier external systems reference. Unlike some other identifiers in Tagnet, the Code is not permanent: it can be changed after creation, but doing so shows a warning because integrations configured with the old Code will stop resolving the scope.
• The system scope can be renamed to your organization's name at any time from its edit page.

See Access Scopes for the complete walkthrough.

Best Practices

Role Assignment

• Start with least privilege: Assign the minimum role needed for someone's job
• Use Operator for daily tasks: Most warehouse staff only need Operator access
• Reserve Admin for IT: Only technical staff who manage the system need Admin
• Use ApiClient for integrations: Don't use human accounts for automated systems

Scope Organization

• Keep it simple: Start with one scope per physical site
• Use the system scope for shared resources: Item types, templates, and common definitions
• Don't over-segment: Too many scopes create management overhead
• Match your org structure: Scopes should reflect how your organization operates
• Pick a stable Code up front: The Code can be changed later, but a rename breaks any integration still configured with the old value. Decide on a short, stable identifier (e.g., chi-wh, dallas-dc) before clicking Create scope, especially if integrations will reference it

Security

• Regular access reviews: Periodically review who has access to what
• Deactivate promptly: Deactivation takes effect immediately. The user's active session is terminated on their next request and their refresh tokens are revoked. Act quickly when someone leaves or changes roles
• Audit sensitive changes: Admin actions are logged for compliance. View the full trail on the Security Events page
• Monitor failed logins: Filter Security Events by UserLoginFailed and UserAccountLocked to detect credential-stuffing or shared-password issues

Frequently Asked Questions

Q: A user says they're locked out. What do I do? A: Their account was locked after too many failed sign-in attempts. On the Users page, find the user. You'll see a yellow Locked chip next to their status. Open the row actions menu and choose Unlock Account. The lock clears immediately. If the lockout keeps happening, check the Security Events page and filter by UserLoginFailed to see what's driving the failures.

Q: A user says they forgot their password. What do I do? A: If email is configured, point them to the Forgot password? link on the login page. They enter their email address and receive a reset link valid for one hour. If email is not configured (or the link expired), use Reset Password from the row actions menu on the Users page to set a temporary password for them, then have them change it on next login. See Email Settings to configure email delivery.

Q: Can a user have multiple roles? A: No, each user has exactly one role. If someone needs capabilities from multiple roles, assign them the higher-privilege role.

Q: Can I create custom roles? A: The built-in roles cover most use cases. Custom roles may be available in future versions.

Q: What happens if I'm not assigned to any scope? A: You'll only see the system scope's shared resources (read-only). Contact your administrator to be assigned to appropriate site scopes.

Q: Can I move data between scopes? A: Yes, if you have access to both the source and destination scopes. This creates an audit trail of the transfer.

Q: How do I know what scope I'm viewing? A: If you can see more than one site scope, a scope filter dropdown appears in the header. When the dropdown shows All Scopes, no filtering is active and you're seeing data from all your assigned sites. If the dropdown shows a specific site name or a count (e.g., 2 Scopes), filtering is active. Scope columns in data lists also show which scope each record belongs to. If you have one site scope (or none), these elements are hidden: everything you see is from your site plus shared resources from the system scope.

Q: Why don't I see scope columns or a scope dropdown? A: If you're assigned to only one site scope, Tagnet hides scope-related UI elements to simplify your experience. You're viewing data from your assigned site plus read-only access to the system scope's shared resources. If you need access to additional sites, contact your administrator.

Q: I changed a user's role or access scopes but they say nothing has changed for them. Do they need to log out? A: No. Role and access-scope changes apply to the user's active session automatically. The change takes effect on their next navigation within the app, or within about two minutes if they are sitting on the same page. If a user wants to see the change immediately without navigating, a full page refresh will also apply it. If the update still hasn't appeared after a couple of minutes, see Permission Changes Not Visible.

Q: What does the lock icon mean on some items? A: A lock icon indicates a shared resource from the system scope that you can view but not edit. These are organization-wide resources (like standard item definitions or templates) managed by administrators. Contact your admin if changes are needed.

Q: I created a scope with the wrong Code. Can I fix it? A: Yes. Unlike some other identifiers in Tagnet, a scope Code is not permanent. Open the scope's edit page and change the Code; Tagnet shows a warning before saving because any integration still configured with the old Code will stop resolving the scope. See Access Scopes for the full explanation of how Code changes work and why the warning matters.