Tagnet Admin Console

The Tagnet Admin Console is a companion application installed alongside the Tagnet server. It is the primary place administrators configure and operate Tagnet on a Windows host: choose the database, edit the most common settings with guided controls, and rotate security keys. Behind the scenes it manages the same configuration files and Windows service you would otherwise touch by hand, so changes are atomic and the service is restarted in one step.

This page is the entry point for administration topics. Start at the top to learn what the Admin Console covers, drop into the Settings reference for what each setting does, and use Advanced configuration when you need file-based overrides, environment variables, or a headless install.

When to use the Admin Console

Use the Admin Console for:

• First-run setup of the server (it presents the one-time setup token).
• Switching between SQLite and SQL Server, or updating the connection string.
• Editing the most common runtime settings (token lifetimes, CORS origins, log level, rate limits, and more).
• Setting the web server port and serving Tagnet over HTTPS with a certificate from the server's certificate store.
• Rotating Data Protection and JWT signing keys.

Edit configuration files or environment variables directly when:

• You are running a headless install (Linux, Docker, or automation that has no desktop session).
• You need to change a setting the Admin Console does not expose (JWT issuer/audience, EF Core log overrides, and similar low-volume keys).
• You manage configuration through your own deployment tooling.

The Admin Console and the file-based methods edit the same appsettings.Production.json file -- you can mix them.

Launching the Admin Console

The installer adds Tagnet Admin Console to the Start menu. It must be run on the Windows server that hosts Tagnet, with administrator privileges (it manages the Tagnet Windows service and writes to C:\ProgramData\Stratum Global\TagNet\).

Home

On a fresh install, a first-run checklist with four steps in order: Database, Web Server, Email Server, and Finish setup in the browser, which holds the one-time setup token you use to authenticate the first-run wizard. The first three rows show the current setting once the console runs as administrator (a single Restart as administrator prompt sits at the top of the list until then). After the wizard completes, the same page becomes a status summary with Open Tagnet: the Database, Web Server, and Email Server rows show their settings with a check mark when the console runs as administrator, and the prompt otherwise.

Database Setup

Selects the database provider (SQLite or SQL Server) and validates the connection. Tagnet uses SQLite by default; switch to SQL Server here if you want to point Tagnet at an existing SQL Server or Azure SQL database. Saving applies the change to appsettings.Production.json and restarts the service. Choose the provider before you start using Tagnet: changing it later connects Tagnet to a different database, and existing records are not copied across.

For SQL Server connection-string format, authentication options, and a full Azure SQL walkthrough, see SQL Server & Azure SQL.

Service Account

Sets the Windows account the Tagnet service logs on as: LOCAL SERVICE (the installer default), a Windows account with a password, or a group Managed Service Account. Needed for Windows Authentication to SQL Server, which sees the service's account rather than yours. Validate checks the account (and, for a Windows account, opens the configured database connection as it); Save grants Log on as a service, the data folder, and the HTTPS private key, reconfigures the service, and restarts it. If the service does not come back, the previous account is restored automatically when it had no stored password (LOCAL SERVICE or a gMSA); a previous Windows account cannot be, because its password is no longer stored anywhere. A separate Update password and restart action covers passwords rotated in Active Directory. See Service Account.

Web Server Setup

Controls how the Tagnet service is reached. HTTP and HTTPS are independent switches, each with its own port, so a server can serve HTTP only (the default), both while readers are moved across, or HTTPS only with the HTTP port left unbound. The page refuses to turn both off. An optional redirect makes a bound HTTP port answer every request with a redirect to HTTPS, readers and API clients included; there are no per-path exceptions in any mode. Below the switches sits the External URL that readers and emailed links use.

Validation checks the certificate the way Kestrel will load it (validity, private key, the service account's access to that key, server-authentication key usage, subject match, trust chain), confirms the ports are free, and confirms the host name resolves. The page grants the service account key access when needed, opens the configured ports in Windows Firewall under console-owned rules, and restarts the service. There is no IIS or reverse proxy. See Web Server Setup for the full procedure, including the no-downtime order for moving an existing server to HTTPS.

Email Setup

Chooses the email provider (None, SMTP, SendGrid, or Azure Communication Services), the From address and display name, and the provider's connection details. Test runs a real connectivity/TLS/authentication check against an SMTP server without sending, or a format check for SendGrid and Azure Communication Services. Save and restart re-runs the checks, aborts if any fail, writes the Mail:* settings with secrets encrypted at rest, and restarts the service. Choosing None disables delivery: invitations and password resets fall back to showing their link in the admin UI. See Email Settings for the full walkthrough.

Tagnet AI

Chooses the AI provider for the built-in assistant (None, Azure OpenAI, or Ollama) and its connection details: endpoint, API key and deployment name for Azure OpenAI, or server URL and model for Ollama. An Advanced section holds the maximum auto-invoke attempts, temperature, and maximum output tokens. Test runs shape checks for Azure OpenAI (https endpoint, key or Managed Identity, deployment name) and a real check for Ollama: it contacts the server and confirms the model has been pulled. Save and restart re-runs the checks, aborts if any fail, writes the AzureOpenAI:* or Ollama:* settings with the API key encrypted at rest, clears the other provider's endpoint, and restarts the service. Choosing None turns the assistant off. See AI Assistant (Tagnet AI) for provider setup and what the assistant can do.

Scheduled Jobs

Controls when each background job runs: the hour of day and the time zone used to interpret the schedule. Hides cron syntax behind a plain dropdown so you can pick 02:00 / America/New_York without writing a cron expression. Changes are hot-reloaded by the running Tagnet service within about a minute; no restart is required. This page sets the schedule only; retention horizons (how long data is kept) are configured on the Policies page in the Tagnet web UI. See Scheduled Jobs for step-by-step instructions.

App Settings

A guided editor for the most common runtime settings, grouped by section: Hosting, Logging, JWT, CORS, Rate Limiting (Global and Device Ingest), and AI Assistant. The editor:

• Shows the effective value for each setting, with a badge indicating whether it comes from the shipped default, your appsettings.Production.json override, or an environment variable.
• Validates input by type (numbers stay within bounds, enums are dropdowns, etc.).
• Writes the file atomically and restarts the Tagnet service in a single operation.
• Surfaces any keys you have customized that the editor does not know about in a read-only Other settings panel, so nothing is invisible.

The Database section on this page is read-only -- those settings are managed on the Database Setup page so connection-string parsing and validation stay in one place. The Email section is likewise read-only, with a Manage in Email Setup hint -- those settings are managed on the Email Setup page. The AI Assistant sections (Azure OpenAI and Ollama) are read-only as well, with a Manage in Tagnet AI hint -- those settings are managed on the Tagnet AI page.

The full list of settings -- including ones the editor does not expose -- is in the Settings reference below.

Services

The state of the Tagnet Windows service with Start, Stop, and Restart, for bouncing the service without services.msc: after editing a setting by hand, when a reader connection appears hung, or when Diagnostics reports it stopped. Stop and Restart ask for confirmation, since every signed-in user is disconnected and readers cannot deliver reads until the service is running again. The buttons need administrator rights; the state is shown either way. Each attempt is recorded in logs\admin-console.log under the data folder. See Services.

Diagnostics

A read-only view of how Tagnet is deployed on this server, in four sections: Service (state and the account it runs as), Versions (the console against the installed Tagnet, and whether they agree), Network (the address devices are given, the ports being listened on, and the firewall rules Tagnet created), and Storage (data folder, free space, database, newest log). Copy puts all of it on the clipboard as plain text, for pasting into a support ticket or a quick question.

It reports only what Tagnet configured or can read directly, and says so when something needs administrator rights rather than showing a default as though it were fact. Nothing secret appears on it: no connection strings, signing keys, API keys, or setup token, because the output is written to be shared. A database is described by its server and database name and the authentication method, never by the string that would let someone connect to it. It deliberately does not report this server's active network profile: determining that reliably is not possible without inference, and a wrong answer sends the reader down the wrong path. Instead it names the symptom that points at a Public network and gives the one command that confirms it.

This page answers questions about the host. Questions about the application itself, such as the version, database provider, and license, are on the About page inside Tagnet.

Collect support bundle

For a deeper support case than the Copy button covers, Collect support bundle packages recent logs, the Event Log, and a connection snapshot into a .zip file you save yourself and attach to an email to support. Nothing is uploaded or sent automatically.

The Save dialog defaults to tagnet-support-<machine>-<yyyyMMdd-HHmmss>Z.zip. The bundle contains:

File	Contents
diagnostics.txt	The Diagnostics page report, as shown above.
logs/tagnet-*.log	The Tagnet service's rolling logs from the last 7 days, newest first, up to 50 MB.
logs/admin-console.log	The Admin Console's own audit log.
eventlog-tagnet.txt	Windows Event Log entries that mention Tagnet from the last 7 days: Service Control Manager entries from the System log, and crash, .NET Runtime, Windows Error Reporting, and MsiInstaller entries from the Application log.
connections.txt	The listeners, peers, and connection states on Tagnet's HTTP and HTTPS ports. No payload data.
manifest.txt	What is in the bundle, what was left out on purpose and why, what could not be collected and why, and a listener-posture finding saying whether HTTP carries credentials in cleartext, so support knows whether a packet capture is safe to ask for.

Log content is scrubbed before it goes in the bundle: the value of any password, pwd, accesskey, accountkey, or sharedaccesskey key in a connection-string-shaped key=value pair is replaced with [REDACTED], and the manifest reports how many replacements were made. Operational data such as item IDs, EPCs, device names, and IP addresses is left in on purpose, since that is what makes the logs useful for troubleshooting.

The bundle deliberately never includes appsettings.Production.json, a packet capture, database contents, or AI assistant transcripts.

Collecting the bundle refuses, and writes nothing, if the destination has less than 200 MB free or if the finished bundle would exceed 100 MB. Collect support bundle works without elevation, but collects less (some files may be unreadable) and the manifest says so; restart the console as administrator first for a complete bundle.

Security → Rotate Keys

Replaces the keys Tagnet uses to encrypt sensitive values (device credentials, API session tokens). Rotation is disruptive and re-keys every device credential, so it should be run deliberately. See Rotate Keys for what happens during rotation, when to run it, and how to roll back.

Security → Recover Account

Resets a Tagnet user's password when no admin-role user can sign in to the web UI. The page generates a 16-character temporary password, forces the user to change it on their next login, clears any account lockout, and revokes all active sessions, in a single database transaction. Use this only when the normal in-app reset path is unavailable. See Recover Account for step-by-step instructions and what the operation changes on the account.

---

Settings reference

This section documents every setting Tagnet uses, organized by area. For each section the table shows the JSON key, the default, and a description. A note at the top of each section says whether the App Settings editor exposes the setting or whether you need to edit appsettings.Production.json (or set an environment variable) directly. See Advanced configuration for how to do that.

Hosting

Controls how the API binds to the network and which hosts it accepts.

Editor: AllowedHosts is exposed in App Settings. Kestrel:Port, Hosting:HttpEnabled, Hosting:HttpRedirectsToHttps, Hosting:ExternalUrl, and the Kestrel:Endpoints:Https block are managed by the Web Server Setup page and shown read-only in App Settings.

Setting	Default	Description
AllowedHosts	*	Comma-separated host header allow list ASP.NET Core enforces. * disables host filtering -- set explicit hostnames in environments that face the public internet.
Hosting:ExternalUrl	(derived)	The base address readers, invitation links, and password-reset emails use to reach Tagnet. Leave unset to derive it from the HTTPS certificate name and port, or from the server's name and HTTP port. Set it when devices reach the server through a different name, NAT, or a load balancer. Hosted and container installs set it with the Hosting__ExternalUrl environment variable.
Kestrel:Port	5000	The HTTP port Kestrel binds to. Can also be set via the ASPNETCORE_URLS environment variable.
Hosting:HttpEnabled	true	Whether the HTTP port is bound at all. Set to false to serve HTTPS only. Ignored, with a startup warning, when no HTTPS endpoint is configured, so the server can never end up listening on nothing.
Hosting:HttpRedirectsToHttps	false	Whether the bound HTTP listener answers every request with a redirect to HTTPS instead of serving it. Applies to readers and API clients as well as browsers. Ignored unless HTTP is enabled and HTTPS is configured.
Kestrel:Endpoints:Https:Url	(unset)	HTTPS bind address, for example https://*:443 (* binds all IPv4 and IPv6 addresses). Present only when HTTPS is enabled.
Kestrel:Endpoints:Https:Certificate:Subject	(unset)	Subject-name match for the certificate in LocalMachine\My. Kestrel loads the latest-expiring match that has a private key.
Kestrel:Endpoints:Https:Certificate:Store	(unset)	Certificate store Kestrel searches. Tagnet writes My, the Personal store.
Kestrel:Endpoints:Https:Certificate:Location	(unset)	Store location Kestrel searches. Tagnet writes LocalMachine.
Kestrel:Endpoints:Https:Certificate:AllowInvalid	false	Allow Kestrel to load a certificate that does not chain to a trusted root on the server (self-signed or private CA).

JWT authentication

Controls how API access tokens are issued and validated. Affects both the JWT Bearer flow and internal session management.

Editor: Jwt:AccessTokenExpirationMinutes and Jwt:RefreshTokenExpirationDays are exposed in App Settings. Jwt:Secret is rotated via the Rotate Keys page. Jwt:Issuer and Jwt:Audience are file-only because changing them invalidates every existing token.

Setting	Default	Description
Jwt:Secret	Auto-generated	Signing key for JWT tokens. Minimum 32 characters. Use the TAGNET_JWT_SECRET environment variable in production.
Jwt:Issuer	TagNet	Token issuer claim. Should match across all instances in a cluster.
Jwt:Audience	TagNetApi	Token audience claim.
Jwt:AccessTokenExpirationMinutes	15	How long access tokens are valid. Shorter is more secure.
Jwt:RefreshTokenExpirationDays	7	How long refresh tokens are valid before re-authentication is required.

The signing-secret resolution order and key-rotation mechanics are in JWT secret management below.

CORS (Cross-Origin Resource Sharing)

Controls which external websites can make browser-based API requests to Tagnet. Server-to-server integrations (API keys, JWT tokens issued to backend services) are not affected by CORS.

Editor: exposed in App Settings.

Setting	Default	Description
Cors:AllowedOrigins	[] (empty)	Array of allowed origin URLs. Empty array allows all origins.

Allow all origins (development or when only server-to-server integrations are used):

"Cors": {
  "AllowedOrigins": []
}

Restrict to specific domains (recommended for production):

"Cors": {
  "AllowedOrigins": [
    "https://erp.example.com",
    "https://dashboard.example.com"
  ]
}

In development mode, CORS is always permissive regardless of this setting.

Logging

Tagnet uses Serilog for structured logging. The default configuration writes to the console and to rolling log files.

Editor: Serilog:MinimumLevel:Default is exposed in App Settings. The per-namespace overrides are file-only.

Tagnet uses Serilog for all log filtering -- the Serilog:MinimumLevel:* keys control actual log output, not the standard ASP.NET Core Logging:LogLevel section, which Serilog supersedes.

Setting	Default	Description
Serilog:MinimumLevel:Default	Information	Minimum log level for application messages. Options: Verbose, Debug, Information, Warning, Error, Fatal.
Serilog:MinimumLevel:Override:Microsoft.AspNetCore	Warning	Log level for ASP.NET Core framework messages. Keep at Warning unless debugging framework issues.
Serilog:MinimumLevel:Override:Microsoft.EntityFrameworkCore	Warning	Log level for Entity Framework Core. Set to Information or Debug to see model-building and change-tracking details.
Serilog:MinimumLevel:Override:Microsoft.EntityFrameworkCore.Database.Command	Fatal	Controls SQL query logging. Set to Information to see every SQL statement executed. Effectively disabled by default to reduce log volume.

To enable EF Core SQL logging temporarily, override in appsettings.Production.json:

"Serilog": {
  "MinimumLevel": {
    "Override": {
      "Microsoft.EntityFrameworkCore.Database.Command": "Information"
    }
  }
}

This logs every SQL statement with parameter values. Revert to Fatal when done to avoid excessive log volume.

Rate limiting

Built-in rate limiting protects the API from excessive requests.

Editor: every key in this section is exposed in App Settings.

Global rate limit

Applies to all API requests, partitioned by API key or client IP address.

Setting	Default	Description
RateLimiting:Global:PermitLimit	1000	Maximum requests allowed per window.
RateLimiting:Global:WindowMinutes	1	Duration of the rate limit window in minutes.

Device ingest rate limit

Applies to device ingest endpoints (/api/v1/ingest/*), partitioned by device ID or client IP. This is layered on top of the global limit.

Setting	Default	Description
RateLimiting:Ingest:PermitLimit	100	Maximum requests per device per window.
RateLimiting:Ingest:WindowMinutes	1	Duration of the rate limit window in minutes.
RateLimiting:Ingest:QueueLimit	10	Number of excess requests to queue (processed oldest-first) before rejecting. 0 disables queueing.

For high-throughput environments with many readers reporting simultaneously, increase Ingest:PermitLimit to avoid 429 responses. A site with readers sending bulk tag reads every few seconds may need 500 or higher.

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header and a JSON body containing error, message, and retryAfterSeconds fields. Clients and devices should back off and retry after the indicated delay.

Database

Tagnet supports two database providers. The provider and connection string are managed through the Database Setup page in the Admin Console; they appear here read-only as a summary.

Editor: exposed (read-only) in App Settings. Use the Database Setup page to change them.

Setting	Default	Description
DatabaseProvider	Sqlite	Database provider to use. Accepted values: Sqlite, SqlServer.
ConnectionStrings:DefaultConnection	(see below)	Connection string for the selected provider.
Database:PreMigrationBackupsToKeep	3	SQLite only. How many upgrades to keep automatic pre-migration copies for. See Pre-migration backups.

If ConnectionStrings:DefaultConnection is omitted when using SQLite, Tagnet resolves a default path inside the data directory (<data directory>\data\app.db) on first run and writes it back into configuration so all components see the same value.

For SQL Server connection-string format, authentication options, and Azure SQL Managed Identity setup, see SQL Server & Azure SQL.

Security note: Never put database credentials in appsettings.json. Use appsettings.Production.json (outside the web root) or the ConnectionStrings__DefaultConnection environment variable.

API keys

API keys are managed through the Tagnet web UI on the API Keys tab of the Users page. There are no appsettings keys for API keys; permissions, scopes, and expiration are managed in-app. See the API Keys guide and the API Documentation (admin login required) for endpoint details.

Connection profiles

Connection profiles are managed through the Tagnet web UI on the Connection Profiles tab of the Integrations page. There are no appsettings keys for connection profiles; authentication settings are managed in-app, and secrets are stored encrypted using the same Data Protection key ring as device credentials. See the Connection Profiles guide.

AI Assistant (Tagnet AI)

Tagnet AI is the built-in assistant, powered by Azure OpenAI or a local Ollama server. It is disabled by default and only appears in the UI when a provider is configured. Azure OpenAI takes precedence when both are configured.

Editor: on-premises installs set these on the Tagnet AI page of the Admin Console. App Settings shows them read-only with a Manage in Tagnet AI hint. The feature is still experimental: whether AI features become part of on-prem long-term is undecided, so do not depend on this surface yet.

Setting	Default	Description
AzureOpenAI:Endpoint	"" (disabled)	Azure OpenAI resource endpoint. When empty, the Ollama settings apply instead.
AzureOpenAI:ApiKey	""	API key for authentication. Leave empty to use Managed Identity.
AzureOpenAI:DeploymentName	gpt-5.4-nano	Model deployment name in your Azure OpenAI resource.
AzureOpenAI:MaxAutoInvokeAttempts	10	Maximum function-calling iterations per request.
AzureOpenAI:Temperature	"" (omitted)	Sampling temperature, 0 to 2. Leave blank to omit it from the request.
AzureOpenAI:MaxOutputTokens	4096	Cap on tokens generated per response.
Ollama:Endpoint	"" (disabled)	Local Ollama server URL (e.g. http://localhost:11434). Used only when the Azure OpenAI endpoint is empty.
Ollama:Model	llama3.2	Ollama model name. Must support function calling.
Ollama:MaxAutoInvokeAttempts	10	Maximum function-calling iterations per request.
Ollama:Temperature	"" (omitted)	Sampling temperature, 0 to 2. Leave blank to omit it from the request.
Ollama:MaxOutputTokens	4096	Cap on tokens generated per response (Ollama's num_predict).

For Azure resource creation, authentication options, and prompts, see AI Assistant (Tagnet AI).

---

Advanced configuration

This section is for administrators who need to edit configuration outside the Admin Console: headless installs, settings the editor does not expose, automation, or container deployments.

Configuration overview

Tagnet uses the standard ASP.NET Core configuration system. Settings are loaded in layers, where each layer overrides the one before it:

1. appsettings.json -- base defaults, shipped with the application.
2. appsettings.Production.json -- your custom overrides.
3. Environment variables -- highest priority, recommended for secrets.

You should never edit appsettings.json directly. It is overwritten during application upgrades. Place any custom settings in appsettings.Production.json, which is preserved across upgrades.

File locations

Tagnet stores its data files -- including the Production configuration, database, and logs -- in a platform-specific data directory:

Platform	Data Directory
Windows	C:\ProgramData\Stratum Global\TagNet\
Linux	/var/lib/tagnet/

Within the data directory, the layout is:

<data directory>/
├── appsettings.Production.json   ← your custom overrides
├── data/
│   ├── app.db                    ← SQLite database (when using SQLite)
│   ├── app.db-wal                ← recent changes not yet written into app.db
│   └── app.db-shm                ← shared index for app.db-wal
├── logs/
│   └── tagnet-*.log              ← rolling log files
└── secrets/
    └── jwt-secret.protected      ← auto-generated JWT key

app.db-wal and app.db-shm are part of the SQLite database while the service is running, and are usually removed when it stops cleanly. Treat the three files as one: never copy or replace app.db on its own while the service is running, and when you put a different app.db in place by hand, delete the other two first. To take a copy, use Database Maintenance Backup, which produces a single self-contained file.

The base appsettings.json is in the application installation directory (e.g., C:\Program Files\Stratum Global\TagNet\ on Windows). It is managed by the installer and should be treated as read-only.

How configuration layering works

When Tagnet starts, it loads appsettings.json first, then applies appsettings.Production.json on top. You only need to include the settings you want to override -- everything else falls through to the base defaults.

For example, if appsettings.json contains:

{
  "RateLimiting": {
    "Global": {
      "PermitLimit": 1000,
      "WindowMinutes": 1
    }
  }
}

And your appsettings.Production.json contains:

{
  "RateLimiting": {
    "Global": {
      "PermitLimit": 5000
    }
  }
}

The result at runtime is PermitLimit: 5000 with WindowMinutes: 1 -- your override is applied and the rest of the defaults are kept.

Editing the file directly

To customize a setting by hand:

1. Open appsettings.json in the application installation directory and find the setting you want to change. Note its full key path (e.g., Serilog:MinimumLevel:Default).
2. Open appsettings.Production.json in the data directory. Create it if it does not exist.
3. Copy the relevant JSON structure into the Production file, including parent keys, and set your desired value.
4. Restart the Tagnet Windows service for changes to take effect.

Tip: Keep appsettings.Production.json minimal. Only include settings you have intentionally changed. This makes it easy to see what's customized and avoids conflicts when new defaults are introduced in upgrades.

What happens during upgrades

Item	Behavior
appsettings.json	Overwritten with the new version's defaults. New settings and updated defaults are applied automatically.
appsettings.Production.json	Preserved. Your custom overrides are not modified.
Database (app.db)	Preserved. Migrations run automatically on startup. On SQLite a pre-migration copy is written to the Backups folder first.
Logs	Preserved.
Service Log On account	Preserved. A Windows account or gMSA set on the Service Account page (or in services.msc) is re-applied by the installer, which never reads or stores the password.
Service recovery actions	Reset to the installer's settings: two automatic restarts a minute apart after an unexpected exit. Changes made on the service's Recovery tab are overwritten. See Startup type and recovery.
Service startup type	Preserved. If you set the service to Automatic (Delayed Start) yourself, it stays that way across upgrades.

After upgrading, review the release notes for any new settings you may want to customize. The updated appsettings.json shows what's available.

Choosing an override method

There are two ways to customize settings outside the Admin Console: the Production configuration file or environment variables. Either works -- choose whichever fits your workflow.

	Production File	Environment Variables
Best for	Admins who want all overrides visible in one file	Containerized or scripted deployments
Where to set	appsettings.Production.json in the data directory	OS environment, systemd unit, or container config
Survives upgrades	Yes	Yes (not managed by the installer)
Priority	Overrides appsettings.json	Overrides both config files (highest priority)
Visibility	Easy to review -- open one file to see all customizations	Spread across system config; use printenv or service config to review

You can mix both methods. Use the Production file for general settings like rate limits and logging, and environment variables for secrets like TAGNET_JWT_SECRET.

Environment variable syntax

Environment variables use double-underscore notation for nested JSON keys:

JSON Key	Environment Variable
Jwt:Secret	Jwt__Secret
RateLimiting:Global:PermitLimit	RateLimiting__Global__PermitLimit
Cors:AllowedOrigins:0	Cors__AllowedOrigins__0
Serilog:MinimumLevel:Default	Serilog__MinimumLevel__Default

On Windows (running as a service), set environment variables for the service via the registry or a service wrapper. When running interactively, use System Properties → Environment Variables.

On Linux (systemd), add Environment= lines to the service unit file:

[Service]
Environment=TAGNET_JWT_SECRET=your-secret-here
Environment=RateLimiting__Global__PermitLimit=5000
Environment=Serilog__MinimumLevel__Default=Debug

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart tagnet

Environment variables reference

Variable	Maps To	Notes
TAGNET_JWT_SECRET	Jwt:Secret	Recommended for production JWT signing key
ASPNETCORE_ENVIRONMENT	Runtime environment	Development, Staging, or Production
ASPNETCORE_URLS	Kestrel binding	e.g., http://0.0.0.0:5000
DatabaseProvider	Database engine selection	Sqlite (default) or SqlServer
ConnectionStrings__DefaultConnection	Database connection string	File path for SQLite; ADO.NET connection string for SQL Server
Cors__AllowedOrigins__0	First allowed origin	Array items use index notation
AzureOpenAI__Endpoint	Azure OpenAI endpoint URL	Required to enable Tagnet AI assistant
AzureOpenAI__ApiKey	Azure OpenAI API key	For on-premises deployments; omit for Managed Identity
AzureOpenAI__DeploymentName	Model deployment name	Defaults to gpt-5.4-nano if not set
RateLimiting__Global__PermitLimit	Global rate limit	Requests per window (default: 1000)
RateLimiting__Ingest__PermitLimit	Ingest rate limit	Requests per device per window (default: 100)
Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore	EF Core log level	Set to Information to enable EF logging

JWT secret management

The JWT signing secret is resolved in this order:

1. Environment variable TAGNET_JWT_SECRET -- recommended for cloud and containerized deployments.
2. Encrypted local storage -- auto-generated on first run, stored using the ASP.NET Core Data Protection API at <data directory>\secrets\jwt-secret.protected.
3. Configuration file -- fallback to appsettings.json (not recommended for production).

Security note: Never commit a real JWT secret to source control. The default value in appsettings.json is a placeholder that triggers auto-generation.

To replace the secret on a running install (and the rest of the Data Protection key ring), use Security → Rotate Keys in the Admin Console. See Rotate Keys for the full procedure.