Configuration & Admin

AgentWatch is administered from a web console, with a small set of environment variables set at deploy time. The console covers everything an organization administrator needs; a platform-level super administrator additionally sees across organizations.

What is configured at deploy time?

Environment variables covering the database connection, service ports, session and encryption secrets, credentials for any local analysis model, the detection-model size, and backup secrets. Everything else — providers, models, policies, budgets, routes, identity, and users — is runtime configuration managed in the console and stored in the database, so promoting between environments does not require a config-file diff.

What do administrators manage in the console?

• Providers and keys — add providers, pool multiple keys each, set per-key concurrency and rate limits, test keys against the live provider, and schedule rotation.
• Models — expose which models are available to which teams, set per-organization aliases, and retire models without breaking existing consumers.
• Organizations, teams, and employees — the full hierarchy, with CSV bulk import, per-employee keys and budgets, and pause/resume of access.
• Budgets and rate limits — budgets at four tiers with daily and monthly caps, alert thresholds, and admin overrides with expiry; employee budgets are enforced at the gateway always, team budgets when Enforce team budgets is enabled.
• DLP and guardrail policies — detection categories, custom recognizers, confidence thresholds, severity overrides, and per-policy actions.
• Gateway routes — path patterns, upstream targets, transformations, timeouts, per-route authentication and allowlists, with import, export, clone, and reorder.
• Compliance frameworks — select the frameworks that apply and have the matching controls and retention activate together.
• Identity — SSO providers, group-to-team mapping, and SCIM provisioning.
• Roles and permissions — named per-organization roles built from fine-grained permission keys.

How does identity administration work?

A single hub-and-spoke wizard walks an administrator through vendor selection (Microsoft Entra ID, Okta, Google Workspace, Auth0, GitHub, generic OIDC, generic SAML, or Active Directory/LDAP), protocol setup, group-mapping mode, and a connection test before enabling. Drafts can be saved mid-configuration, and auto-create and enabled toggles are set per provider.

Group-to-team mapping is unified across OIDC, SAML, and LDAP, with three modes: off (users get a default role), automatic (directory group names are parsed by a rule and teams are created on the fly with a budget template), or mapped (administrator-defined group-to-team rules with role, budget template, and priority). Mappings apply at first login and update memberships on subsequent logins.

SCIM v2 provisioning is available per organization, with named tokens shown once, usage telemetry, expiry, and revocation — so joiner/mover/leaver flows are driven by the directory rather than by hand.

How granular are permissions?

AgentWatch has two role systems, and the distinction matters when you are deciding who can do what.

The one that governs the console and the admin API has exactly three roles:

Role	Scope	What it means
Super administrator	the whole platform, every organization	sees and changes anything
Administrator (tenant admin)	one organization	full control of that workspace
User	themselves	uses the gateway; no admin pages

This is what nearly every administrative endpoint checks. You grant it per employee at Employee Management → Edit employee → Make as admin, which an organization may hold any number of. An employee with no login account cannot be promoted until a password reset creates one — the checkbox is disabled and says so. It is also assignable from your identity provider’s group claim at sign-in, which is the usual route for an SSO deployment.

The second system is a finer-grained, per-organization set — Owner, Administrator, Manager, Viewer, plus custom roles — built from individual permission keys:

	users.read	users.write	users.delete	roles.manage	billing.manage	settings.update	reports.view	audit_logs.view	api_keys.manage	models.configure
Owner	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Administrator	✓	✓	—	✓	—	✓	✓	—	✓	✓
Manager	✓	—	—	—	—	✓	✓	—	—	—
Viewer	✓	—	—	—	—	—	✓	—	—	—

So Manager means: read the people list, see usage reports, change organization settings — but not create, edit or delete users, and not manage roles, keys, models or billing. A team lead who should watch spend and tune settings without touching the roster.

⚠ Know the limit of the second system. These permission keys currently govern user administration, role management and audit-log viewing — not the whole console. Everything else is gated by the three-role model above, so an employee whose role is Administrator holds full tenant-admin power over their organization regardless of which named role they also hold. Treat Owner / Manager / Viewer as refinements within user and audit administration, not as a general-purpose permission system, and do not rely on Viewer to keep someone out of a settings page.

Is there a recommended secure baseline?

Yes. A hardened baseline preset is documented and can be applied at deploy time: all guardrails enabled, maximum audit retention, IP allowlisting on, mutual TLS required for endpoint agents, and external guardrail engines enabled. It is the recommended starting point for regulated deployments, from which exceptions are made deliberately rather than accumulated by default.

Can the platform be demonstrated before real keys are wired up?

Yes. A demo mode — on by default for new installations and toggleable per user — populates every console surface with realistic generated data: employees, teams, providers, audit records, security events, session history, usage metrics, fleet health, insider-risk standings, and dashboards. Nothing is written to the database, so it is available the moment the image runs, and it can be disabled globally at install time for production.

What is the operational surface?

A health endpoint for orchestrator and load-balancer probes; graceful shutdown that flushes in-flight work before closing; automatic schema application and backfill at boot so upgrades need no manual migration; self-healing that reaps stale jobs and re-probes tripped circuit breakers; and diagnostics endpoints for support investigations. Logs and data live on mounted volumes.

Where is everything configured?

What	Where
Employees, keys, key type	Employee Management
Teams, team budgets, model access	Team Management
Budgets and overrides	Budget Management
DLP, guardrails, compliance frameworks	Settings → Company Policy
Providers, models, pricing	Settings → Providers
Gateway routes, tenant routing	Settings → Gateway Routes
SSO, SCIM, enrollment portal	Settings → Single Sign-On
Event pipeline, database, notifications	Settings → System
Audit log	Settings → Audit Logs
Organizations, plans, cross-tenant	Platform Admin (super-admin only)

Which settings are platform-wide and which are per organization?

This distinction causes more confusion than any other: a handful of settings are process-wide — the event pipeline, the system LLM, session vector config — because a single process serves every tenant. They are stored on the platform row and can only be written by a super-admin. Everything else is per organization, and a tenant admin owns it.

If a tenant admin saves company settings, the platform fields in that payload are dropped rather than written, and a genuine attempt to change one is refused and recorded in the audit log.

A super-admin with no organization selected is editing the platform row — the defaults every organization inherits. The console names the row on screen so this is never ambiguous.

How do I change a setting safely?

1. Read the current value first (GET the settings, or note it in the console).
2. Change one thing.
3. Verify with a real request rather than by re-reading the form.
4. If it misbehaves, the audit log has a per-field before-and-after diff — that is your rollback instruction.

Settings are cached briefly (about 30 seconds), so a change is live on the next request without a restart, and a change you make will not appear to take effect instantly on every replica.

Common configuration problems

Symptom	Cause	Fix
A saved setting appears not to apply	The settings cache, or you are on a different organization’s row	Wait ~30s; confirm the scope banner
A tenant admin cannot change something	It is a platform-scoped field	A super-admin must change it
A settings save throws an error after an upgrade	A settings column did not migrate	Check the upgrade logs; every column has migration coverage in both dialects
Model changes do not take effect	The per-organization model projection is cached	Create/update/refresh reload it; re-check /api/models/available

Can I apply a setting to every organization at once?

Yes, from 2.0.296 — as an explicit action, and it is switched off until you turn it on.

Why it is not automatic. An organization’s settings are read as a whole, not merged field by field with the platform defaults. So an organization that has any settings of its own does not inherit a platform-level value — and that is true of every setting, not a particular one. We deliberately did not change that resolution: for most settings a stored value is indistinguishable from one nobody ever touched, so inheriting would silently re-enable things tenants had turned off.

From the console (2.0.297 and later). Sign in as a super administrator and open Settings -> Company Settings. Directly under the Viewing platform defaults banner is a panel titled Apply platform defaults to all organizations. The panel is visible only to super administrators.

1. Tick Allow pushing platform settings to sub-tenants. This is the same switch as platformApplyToAllEnabled, it is off on every deployment until you tick it, and the endpoint refuses while it is off.
2. Choose what to push: Data protection (DLP), Content guardrails (including gibberish labels and thresholds), Model access default, Rate limits, WAF custom rules — or name any other settings field in Other fields.
3. Press Preview changes. You get a table of the organizations that would change and the before/after for each field. Nothing is written.
4. Press Apply to all organizations and confirm. The panel reports how many organizations were written, and names any that failed.

Note what is not pushed: gateway routes, tenant routing modes and the model catalog are per-organization records, not settings fields, and are managed on their own pages per tenant. This action writes Company Settings fields only. The catalog-facing field that is pushable is defaultModelAccess.

Or over the API (super administrator):

curl -s -X POST "https://<your-agentwatch-host>/admin/company/settings" \
  -H "Authorization: Bearer <super-admin JWT>" -H 'Content-Type: application/json' \
  -d '{"platformApplyToAllEnabled": true}'

See what would change — this writes nothing:

curl -s -X POST "https://<your-agentwatch-host>/admin/company/settings/apply-to-all" \
  -H "Authorization: Bearer <super-admin JWT>" -H 'Content-Type: application/json' \
  -d '{"fields": ["dlpEnabled", "guardrailsBlockOnViolation"]}'

You get the organizations that would change and the before/after for each field. Re-send with "confirm": true to apply.

Guard	Behaviour
Not a super administrator	403
platformApplyToAllEnabled off	409 APPLY_TO_ALL_DISABLED
No fields given	400 FIELDS_REQUIRED — there is no “apply everything”
An unknown field name	400 UNKNOWN_FIELD
Without confirm: true	Preview only; nothing is written

Each organization that changes gets its own audit entry (settings.applied_from_platform) recording the fields and their before/after values. If one organization fails, the rest still apply and the failures are returned rather than swallowed.

Upgrading: the switch is off on every existing deployment, so nothing propagates until you enable it deliberately.

Sources and references

• Deployment prerequisites: Deployment.
• Identity and access in a security context: Security and compliance.