Security

Control who can use each API, App, and Service with security profiles and API keys, and limit request rates.
Framework Docs Menu

The admin UI's Security area manages who can sign in to and call an Instance: Identity providers, Users, API keys, the admin accounts, and Trusted Publishers. The security profiles that decide who can reach what are under Config > Access with the Zones, since Deployments carry them. Packages declare what can be protected, Identity providers sign people in and authenticate requests, and administrators grant access with security profiles. To limit what modules can reach, see Zones.

Client A browser, script, application, AI assistant, or another Instance
HTTP request, with an API key or sign-in cookie
Instance
IdentityWho is calling? API keys, users, OpenID Connect, LDAP, or a token
401 No valid key or session for a protected resource
Security ProfilesMay this caller use this API endpoint or App page?
403 The caller's roles don't allow it
Your API or AppRuns your code, which calls Client.Services, Functions, or other APIs
Workers and Functions start here, with no caller
ZoneMay this module reach that Service, API, Function, or Volume?
403 Zone Access Denied, only for modules in a Zone
RouterWhich Service handles this kind of data? Tries the Route's Targets in order
405 No Service for this kind of data on the Router
ServiceReads or writes using the connection details set by IT
503 / 504 The backend is unavailable or timed out
Databases, Brokers, and Files SQL Server, Redis, MQTT, RabbitMQ, the file system, or another Instance
Profiles decide who can come in; Zones decide what each module can reach out to; Routers decide where data goes.

Security Pages

PageWhat you can do
Security Profiles (Config > Access)Add a profile (ID, Description, Identity Provider, and Priority), then add Assignments that grant roles and permissions on resources. An Identity Provider of None makes the profile's resources public, whatever other profiles require (ex. an App's sign-in page).
API KeysCreate an API key with a Name, Description, Roles, and Expiration (30 days, 90 days, 1 year, or Never). The key is shown only once. Revoke a key to disable it.
UsersAdd, edit, disable, sign out, and delete users of the built-in Users provider, and choose their Sign In Page.
ProvidersAdd and configure Identity providers (API Keys and Users, which are built in, OpenID Connect, and LDAP), and Test Sign In. Shows the Redirect URI to register with your provider.
Admin Accounts, Admin RolesThe accounts that sign in to the admin UI and what their roles allow (see Admin Accounts and Roles). Only an Owner sees these pages.
What is Public?Every endpoint that works without signing in, and why. This machine only lists the System API endpoints that work without signing in only from the Instance's own machine.
Access CheckTest whether an identity, roles, or an API key can reach a resource, and see the reason.
Audit LogA record of changes to Packages and configuration files: when, what changed, who made it, and the file hash before and after. Contents aren't stored, since configuration files can hold secrets. Verify checks the chain of records, and Download saves the log.
Zones, Zone Map (Config > Access)Limit what modules can reach through the Instance (see Zones).

Audit Log

Security > Audit Log records each change with its source. The first start adds one Baseline record, and changes are recorded from then on.

SourceMeaning
AdminMade in the admin UI, with the signed in username
SystemApiMade through the System API or MCP Server, with the identity if the caller had one
ModuleMade by a Package using a Module Token
InstanceMade by the Instance itself, such as a Package update
DetectedFound by comparing the files on disk, so who made the change isn't known. This includes files edited directly and Deployments
  • Each record includes the hash of the one before it, so Verify shows if a record was edited or removed. It can't detect records removed from the end of the file, or the whole file being replaced, by someone with full access to the machine, so copy the log somewhere else regularly.
  • The log is audit.jsonl in the configuration profile folder. Records are never removed automatically, Log History settings don't affect them, and Deployments and backups leave the file out.
  • If a record can't be written, the error is logged and the change still goes through.
  • The System API serves the log at /_instances/audit and the check at /_instances/audit/verify, controlled by the system:audit resource.

Resources

Profiles grant access to resources by ID. An assignment can end in * to match a prefix (ex. api:orders-api:*).

ResourceIDPermissions
API endpointapi:{apiId}:{controllerId}:{endpointId}Those listed on the endpoint with [TrakHoundPermission]
App pageapp:{appId}:{pageId}
Service operationservice:{serviceId}:{family}:{operation}read, or write for uploads, deletes, publishes, and non-queries
System API areasex. system:functions, system:logs, system:volumes, system:mcp, system:api-catalogread, write
Calls that modules make while handling an API request or App page run as the signed-in caller, so the caller's permissions apply. Calls from Workers and Functions, which have no caller, are trusted (use Zones to limit them).

Unprotected Resources

What happens to a resource that no profile covers depends on the kind of resource:

  • APIs and Apps are public.
  • System resources (system:*, including the MCP Server) and Service operations can only be used from the Instance's own machine. Requests from other machines get 403 Forbidden.

To use the System API, Services, or the MCP Server from another machine (ex. a client application, another Instance's HTTP Service, or an MCP client), add a profile that covers them and send an API key, or turn on Settings > Interfaces > Unprotected Remote Access on a trusted network. Behind a reverse proxy on the same machine, set Trusted Proxies so requests are seen as coming from the client, not the proxy. Use What is Public? to review what can be reached without signing in.

Protecting Your Package

Add [TrakHoundPermission] to an API endpoint. A caller needs one of the listed permissions in a matching profile assignment, or *:

[ApiDelete("{id}")]
[TrakHoundPermission("write")]
public async Task<TrakHoundApiResponse> Delete([FromRoute] string id)
{
    ...
}
  • In an App, wrap parts of a page in <TrakHoundProtectedView Permissions="..."> to show them only to users with those roles.
  • Inside an endpoint, TrakHoundSecurityContext.Current?.Identity holds the caller's UserId, Name, Roles, and provider, and TrakHoundSecurityContext.Current.Authorize(resourceId, permission) runs your own checks.

Signing In and API Keys

  • Interactive sign-in - OpenID Connect, LDAP, and the built-in Users providers sign users in at /_identity/signin and issue an encrypted cookie session.
  • API keys - The built-in api-keys provider accepts hashed keys sent as an X-API-Key: thk_... header or as Authorization: Bearer thk_....
  • Bearer tokens - The OpenID Connect provider also accepts Bearer tokens issued by your identity server.
  • Module Tokens - Let a process started by a module call the System API as that module. See Zones.
curl -H "X-API-Key: thk_..." http://localhost:8472/api/orders

After 5 wrong passwords from one address (or 20 for one username from any address), sign-in is locked for 1 minute, then twice as long each time it happens again, up to 15 minutes. This applies to the admin UI and to Identity providers that take a username and password (ex. LDAP and Users). While locked, sign-in returns 429 Too Many Requests.

Rate Limits

Rate Limits stop one caller, such as a script polling too fast or an AI client in a loop, from slowing down the Instance or the databases behind its APIs for everyone else. They are off by default. Turn them on in Settings > Rate Limits; changes apply when saved.

AreaLimitsDefaults
apiHTTP requests to API endpoints600 per 60 seconds, 20 at a time
systemApiHTTP requests to the System API600 per 60 seconds, 20 at a time
mcpToolsMCP Tool calls120 per 60 seconds, 4 at a time
rateLimits:
  enabled: true
  api:
    permitLimit: 600      # requests per window (0 = no limit)
    window: 60            # seconds
    concurrencyLimit: 20  # requests at the same time (0 = no limit)
  • Each caller is counted separately: by identity (ex. an API key), or by IP address when anonymous.
  • Requests over a limit get 429 Too Many Requests with Retry-After. MCP Tool calls get a Tool error instead, which an AI client can act on.
  • Calls made inside the Instance (Functions, Workers, Apps, and Module Tokens), the admin UI, Apps, and health checks are not limited, and streams don't count toward concurrency.
Rate Limits protect against mistakes, not attacks. Use a reverse proxy or gateway to block heavy traffic from the internet.

Admin Accounts and Roles

Admin accounts sign in to the admin UI. The first account is an Owner, created on the Instance's machine (see Admin Account), and an Owner adds the others on Security > Admin Accounts with one or more roles. Roles apply to the admin UI only: the System API and MCP Server are controlled by security profiles.

RoleWhat it can do
OwnerEverything, including the admin accounts and roles.
PackagesInstall, update, and uninstall Packages, and configure and use Apps, APIs, Functions, and Workers. No Services, Routers, Settings, Variables, Deploy, Security, or Licenses.
Security OperatorAdd and change Users and API keys, and view security profiles, Identity providers, and the Audit Log.
ViewerView everything except the admin accounts, and change nothing.
  • Your own roles - On Security > Admin Roles, an Owner adds roles that set None, View, or Change for each area, and can limit which roles an admin may give Users and API keys (ex. operators, line-1-*).
  • Limited to Zones - A role on an account can be limited to Zones, so it only manages the Apps, APIs, Functions, and Workers in those Zones, and the Service data and Volume files their Rules allow. A new configuration must land in one of its Zones.
  • Access to the Instance itself - Only an Owner can give a User or API key a role that a security profile grants on the System API (system:*) or Services (service:*), or change a profile assignment on those resources.
  • What a restricted admin sees - Areas its roles don't cover aren't in the navigation, and buttons that change something are hidden on pages it can only view.
  • There's always an enabled Owner. If no Owner can sign in, set-admin on the Instance's machine adds one or resets one's password. Changes to admin accounts and roles are in the Audit Log.
Roles guard against changing something by accident, or something you weren't asked to manage. They aren't a barrier against someone who can install Packages, since a Package is code that runs in the Instance.

Instance Hardening

  • Admin accounts - The first one is created only on the Instance's machine, never from the browser (see Admin Account). Give the others only the roles they need.
  • Allowed Addresses - Config > Settings > Interfaces > Admin Access (adminAllowedAddresses) limits the admin UI to the computers that manage the Instance. Others get 404 Not Found, and the Instance's own computer is always allowed. Behind a reverse proxy, set Trusted Proxies first.
  • Request size - Request bodies are limited to 256 MB by default (maxRequestBodySizeMb).
  • Key files - The Instance limits the key for encrypted values, the sign-in cookie keys, and the admin account files to its own user when it starts.
  • Separate Admin port - Set adminHttpPort (and optionally adminHttpAddress) to serve the admin UI and System API on their own port, so they can be firewalled apart from Apps and APIs.
  • Turn off what you don't use - The admin UI, System API, MCP Server, and serving Apps or APIs over HTTP can each be turned off (see Instances). A disabled admin UI returns 404.
  • Per-API HTTP access - Set httpEnabled: false on an API configuration to serve it only to other modules.
  • Secrets - Secret parameters and Configuration Variables are encrypted (see Configuration).