# Security

> Control who can use each API, App, and Service with security profiles and API keys, and limit request rates.

URL: https://www.trakhound.com/docs/trakhound-framework/security

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](https://www.trakhound.com/docs/trakhound-framework/identity) sign people in and authenticate requests, and administrators grant access with security profiles. To limit what *modules* can reach, see [Zones](https://www.trakhound.com/docs/trakhound-framework/zones).

Diagram: A request from a client is identified, checked against security profiles, handled by your API, which calls a Service through its Client. The call is checked against the module's Zone, sent by a Router to a Service, and reaches a database or broker. Each step can refuse the request with its own status code.

## Security 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](https://www.trakhound.com/docs/trakhound-framework/identity#users), 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](https://www.trakhound.com/docs/trakhound-framework/security#admin-accounts)). 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](https://www.trakhound.com/docs/trakhound-framework/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.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:*`).

| 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` |

> 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](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/installation#reverse-proxy) 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](https://www.trakhound.com/docs/trakhound-framework/identity#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](https://www.trakhound.com/docs/trakhound-framework/zones#module-tokens).

```
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 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](https://www.trakhound.com/docs/trakhound-framework/installation#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](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/installation#admin-account)). Give the others only the [roles](https://www.trakhound.com/docs/trakhound-framework/security#admin-accounts) 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](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/configuration#secrets)).
