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.
401 No valid key or session for a protected resource403 The caller's roles don't allow itClient.Services, Functions, or other APIs403 Zone Access Denied, only for modules in a Zone405 No Service for this kind of data on the Router503 / 504 The backend is unavailable or timed outSecurity Pages
| Page | What 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 Keys | Create 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. |
| Users | Add, edit, disable, sign out, and delete users of the built-in Users provider, and choose their Sign In Page. |
| Providers | Add 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 Roles | The 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 Check | Test whether an identity, roles, or an API key can reach a resource, and see the reason. |
| Audit Log | A 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.
| Source | Meaning |
|---|---|
| Admin | Made in the admin UI, with the signed in username |
| SystemApi | Made through the System API or MCP Server, with the identity if the caller had one |
| Module | Made by a Package using a Module Token |
| Instance | Made by the Instance itself, such as a Package update |
| Detected | Found 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.jsonlin 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/auditand the check at/_instances/audit/verify, controlled by thesystem:auditresource.
Resources
Profiles grant access to resources by ID. An assignment can end in * to match a prefix (ex. api:orders-api:*).
| Resource | ID | Permissions |
|---|---|---|
| API endpoint | api:{apiId}:{controllerId}:{endpointId} | Those listed on the endpoint with [TrakHoundPermission] |
| App page | app:{appId}:{pageId} | |
| Service operation | service:{serviceId}:{family}:{operation} | read, or write for uploads, deletes, publishes, and non-queries |
| System API areas | ex. system:functions, system:logs, system:volumes, system:mcp, system:api-catalog | read, write |
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 get403 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?.Identityholds the caller'sUserId,Name,Roles, and provider, andTrakHoundSecurityContext.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/signinand issue an encrypted cookie session. - API keys - The built-in
api-keysprovider accepts hashed keys sent as anX-API-Key: thk_...header or asAuthorization: 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.
| Area | Limits | Defaults |
|---|---|---|
api | HTTP requests to API endpoints | 600 per 60 seconds, 20 at a time |
systemApi | HTTP requests to the System API | 600 per 60 seconds, 20 at a time |
mcpTools | MCP Tool calls | 120 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 RequestswithRetry-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.
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.
| Role | What it can do |
|---|---|
| Owner | Everything, including the admin accounts and roles. |
| Packages | Install, update, and uninstall Packages, and configure and use Apps, APIs, Functions, and Workers. No Services, Routers, Settings, Variables, Deploy, Security, or Licenses. |
| Security Operator | Add and change Users and API keys, and view security profiles, Identity providers, and the Audit Log. |
| Viewer | View 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-adminon the Instance's machine adds one or resets one's password. Changes to admin accounts and roles are in the Audit Log.
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 get404 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 optionallyadminHttpAddress) 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: falseon an API configuration to serve it only to other modules. - Secrets - Secret parameters and Configuration Variables are encrypted (see Configuration).