API Keys

API keys allow external systems to authenticate with the Tagnet REST API for machine-to-machine integrations. Each key has its own role, access scopes, and lifecycle controls.

Overview

Use API keys when you need to connect external systems to Tagnet without using a human user account. Common integration scenarios include:

Scenario	Description
ERP / WMS sync	Push or pull inventory data between Tagnet and your enterprise system
Reporting dashboards	Read inventory snapshots, transactions, and device status
Custom applications	Build tools that interact with Tagnet programmatically
Automated workflows	Trigger inventory moves or data exports on a schedule

API keys are separate from user accounts. They use a dedicated authentication header (X-Api-Key) and have their own role and scope assignments.

Tip: API keys authenticate systems calling into Tagnet. If instead you need Tagnet to call out to an external system, for example from a workflow's Send HTTP action, see Connection Profiles.

Permissions

Action	Required Role
View and manage API keys	Admin

Only administrators can create, edit, rotate, or revoke API keys. API keys themselves cannot manage other API keys.

The API Keys Page

Open the API Keys tab of the Users page to view all keys in your system.

The data grid shows:

Column	Description
Name	Descriptive label for the key (e.g., "ERP Integration")
Role	The role assigned to this key (ApiClient, ApiInventory, or ApiIntegration)
Status	Current state: Active, Inactive, Expired, or Revoked
Last used	When the key was last used to authenticate, or "Never"
Expires	Expiration date, or "Never" if no expiration is set
Created	When the key was created
Actions	Available operations for the key

Use the search bar to filter by name, or the filter bar's Role and Status dropdowns to narrow the list further. Revoked keys are hidden by default; toggle Show revoked keys in the filter bar to include them. Click a row (or choose Details from its actions menu) to open the key's detail page, which also shows its Key Prefix for identification alongside its role, access scopes, and validity. Its Permissions section lists every permission by category, with a check mark beside each one the key's role grants, so you can see what the key cannot do as well as what it can.

API Key Roles

API keys use dedicated roles that are separate from user roles:

Role	Access Level	Use Case
ApiClient	Read-only	Dashboards, reporting, data extraction
ApiInventory	Read, plus add and update inventory	Commission tags, record movements, and place items against an existing catalog
ApiIntegration	Read and write, including the catalog	ERP sync, inventory updates, catalog and device management

ApiClient Permissions

ApiClient keys can view devices, inventory, locations, items, types, custom fields, and scan events. They cannot create, modify, or delete any data.

ApiInventory Permissions

ApiInventory keys have all ApiClient read permissions plus the ability to add and update inventory: commission tags, map tags to instances, edit inventory, and record movements. They cannot change the catalog (items, types, custom fields, locations) or manage devices, users, roles, or settings. Use this role for a print or production station that creates inventory against a catalog someone else maintains.

ApiIntegration Permissions

ApiIntegration keys have all ApiClient permissions plus the ability to manage devices, manage item types, location types, and device types, edit and delete inventory, import inventory, manage locations, manage items, and manage custom fields. They cannot manage users, roles, or system settings.

Note: Access scopes still apply. An ApiIntegration key can only read or write data within the scopes assigned to it, regardless of the permissions its role grants.

Creating an API Key

1. On the API Keys tab of the Users page, choose API Key from the Add menu, which opens the create page
2. Enter a descriptive Name (e.g., "ERP Integration - Production")
3. Choose a Role by clicking its card. The three API roles sit side by side, each showing what it Reads and what it Changes, so you can compare them before you pick
4. Select one or more Access Scopes to control which data the key can access
5. Optionally set an Expiration Date
6. Click Create

After creation, the page itself changes to show the full API key. This is the only time the raw key is shown, and it's revealed on this page rather than a dialog you could accidentally dismiss. Copy it immediately and store it securely.

Important: Tagnet stores only a SHA-256 hash of the key. If you lose the raw key, you cannot retrieve it. You must rotate or create a new key.

Using the Key

Include the key in the X-Api-Key header of your HTTP requests:

GET /api/v1/inventory-items
X-Api-Key: tnet_your-key-here

How API key actions appear in the UI

When a record is created or updated through an API key, the Created by and Updated by audit fields throughout Tagnet show the key's name followed by "(API key)". For example, a key named "ERP Integration" appears as "ERP Integration (API key)". This makes it easy to see at a glance which integration touched a record, rather than showing "Unknown". If the key has since been deleted, the display shows "Deleted API key".

Editing an API Key

Choose Edit from the actions menu to open the key's edit page and modify:

• Name: Update the descriptive label
• Role: Change between ApiClient, ApiInventory, and ApiIntegration
• Access Scopes: Add or remove scope assignments
• Expiration Date: Set, change, or clear the expiration

Editing a key does not change the key value itself. Existing integrations continue to work with the same key.

Rotating a Key

Key rotation replaces an existing key with a new one while providing a grace period for migration. This avoids downtime when updating integrations.

1. Choose Rotate Key from the actions menu, which opens the rotate page
2. Select a Grace Period, which sets how long the old key continues to work:
   • 1 hour (for quick updates)
   • 24 hours (default, recommended)
   • 3 days
   • 7 days
3. Click Rotate Key
4. The page changes to show the new raw key, shown only this once for the same reason as at creation. Copy it and update your integration before leaving the page.

During the grace period, both the old and new keys are valid. After the grace period, the old key expires automatically. The new key inherits the same name, role, and scope assignments.

When to Rotate

• Scheduled rotation: Rotate keys periodically as a security best practice
• Staff changes: When someone with access to the key leaves
• Suspected compromise: Rotate immediately with a short grace period (or revoke if urgent)

Disabling and Enabling a Key

To temporarily stop a key from working without destroying it:

1. Click Disable in the actions menu
2. Confirm the action

The key immediately stops authenticating. To re-enable it later, click Enable and confirm.

Use this for planned maintenance windows, temporary integration pauses, or investigating suspicious activity.

Revoking a Key

Revoking permanently deactivates a key. This cannot be undone.

1. Click Revoke in the actions menu
2. Confirm the action

The key immediately stops working. Revoked keys remain visible in the list (toggle Show Revoked to see them) for audit purposes but cannot be re-enabled.

Revoke a key when:

• An integration is permanently retired
• A key is compromised and you need immediate shutdown (rather than rotation with a grace period)
• Cleaning up unused keys

Security

Key Storage

API keys are never stored in plaintext. Tagnet stores only the SHA-256 hash and the first 12 characters (prefix) for identification. The full raw key is displayed exactly once at creation or rotation.

Lockout Protection

If the same inactive, revoked, or expired API key is presented 25 consecutive times, Tagnet locks the key for 15 minutes. This prevents someone holding a deactivated key from repeatedly probing the system to detect if (or when) the key gets re-enabled or re-issued. An administrator can manually unlock the key before the 15-minute window expires.

What this lockout does not protect against: random key guessing. A guessed key that doesn't match any stored key hash never increments any counter. Tagnet returns "Invalid API key" immediately. For that threat, rely on the per-key request rate limit (1,000 / minute) plus your network-edge controls (WAF, IP allowlists, etc.).

Both the automatic lockout and the manual unlock are recorded in the Security Events log: UserApiKeyLocked (actor type System) when the threshold is tripped, and UserApiKeyUnlocked (actor: the administrator) when a key is manually unlocked.

Access Scope Enforcement

API keys are strict: they can read and write only the access scopes explicitly assigned to them. Unlike user accounts, an API key never receives implicit access to the system scope, so you can issue a key that is locked to a single site. If a key needs to read shared reference data (types, items, and other definitions that live in the system scope), assign it the system scope explicitly alongside its site scope. See Access Scopes for how shared and site-specific data is organized.

Rate Limiting

API requests are rate-limited to 1,000 requests per minute per API key. Exceeding this limit returns HTTP 429 (Too Many Requests) with a Retry-After header.

Audit Trail

Every security-relevant API key operation is written to the Security Events log with a timestamp and the acting administrator's identity. The following events are recorded:

Operation	Security Event
Key created	UserApiKeyCreated
Key regenerated	UserApiKeyCreated (with source: regenerate in Details)
Role, scopes, or expiry changed	UserApiKeyUpdated
Key enabled	UserApiKeyEnabled
Key disabled	UserApiKeyDisabled
Key revoked	UserApiKeyRevoked
Key auto-locked after 25 consecutive uses while inactive / revoked / expired	UserApiKeyLocked (actor type System)
Locked-out key manually unlocked	UserApiKeyUnlocked

Name-only edits do not produce an event. Only changes to role, access scopes, or expiration date are considered security-relevant and emit UserApiKeyUpdated.

Disable vs. revoke: understanding the difference

Both disabling and revoking cut off API access immediately, but they are not the same operation:

	Disable	Revoke
Access cut-off	Immediate	Immediate
Reversible?	Yes, re-enable at any time	No, permanent
Key visible in list	Yes (Inactive status)	Yes (Revoked status, toggle Show Revoked)
Use when	Planned maintenance, pausing an integration, investigating suspicious activity	Integration permanently retired, key compromised, cleanup

Choose Disable when you may need to restore the key later. Choose Revoke only when the key will never be used again. Both actions emit their own security event so the audit log records which operation an administrator performed.

The Details JSON for each event is documented in Security Events.

Best Practices

• Use descriptive names: Include the system name and environment (e.g., "SAP Integration - Production")
• Use the least-privilege role: Choose ApiClient for read-only access, ApiInventory to add inventory without changing the catalog, and ApiIntegration only when the integration must manage the catalog too
• Set expiration dates: Require periodic rotation rather than issuing keys that never expire
• One key per integration: Don't share keys across systems; this simplifies auditing and revocation
• Rotate regularly: Use the built-in rotation feature with a 24-hour grace period so clients can switch keys without downtime
• Monitor usage: Review the Last used column periodically; keys that haven't been used may indicate a retired integration
• Revoke promptly: Remove keys for retired integrations immediately

Frequently Asked Questions

Q: Can I retrieve a key after creation? A: No. Tagnet only stores a hash of the key. If you lose it, rotate the key to generate a new one.

Q: Can an API key manage other API keys? A: No. API key management is restricted to administrators using browser sessions or JWT tokens. This prevents a compromised key from creating or modifying other keys.

Q: What happens when a key expires? A: The key immediately stops authenticating. It remains visible in the list with an "Expired" status. You can create a new key or use rotation to replace it before expiration.

Q: Can I assign a key to multiple scopes? A: Yes. Select multiple access scopes during creation or editing. The key can access data from all assigned scopes.

Q: How do I know if a key is being used? A: Check the Last used column on the API Keys page. It shows the timestamp of the most recent successful authentication.

Q: What's the difference between disabling and revoking? A: Disabling is temporary and reversible: the key can be re-enabled. Revoking is permanent: the key can never be used again. Disable for temporary pauses; revoke for permanent removal.

Q: Can I use API keys with the Scalar API documentation? A: The Scalar documentation page (/scalar/v1, opened with Open API reference on the Integrations Overview tab) is only accessible to logged-in administrators. You can test endpoints there using your browser session, then use API keys for actual integrations.