Security & Permissions
The One Agents is built on the same security architecture as every other product in The One Stack. This section covers authentication, multi-tenancy, agent execution permissions, and audit logging.
Authentication
Hub SSO (Browser Sessions)
The Agents console authenticates via Hub SSO. When you open The One Agents from the waffle menu, Hub issues a short-lived JWT that scopes all requests to your organization. No separate login is required.
The JWT includes:
org_id— your organization identifier (all data read/write is scoped to this)user_id— the authenticated userroles— your org-level roles (used for permission checks)jti— a unique token ID for session revocation
Service-to-Service (X-Integration-Key)
Server-to-server API calls authenticate using the X-Integration-Key header. Integration keys are issued in Hub under Settings → Integrations and are scoped to a single organization.
GET /api/agents
X-Integration-Key: ik_live_abc123...
Integration keys have no expiry by default but can be rotated or revoked in Hub at any time. All API calls made with an integration key are logged with the key ID.
Multi-Tenancy and Data Isolation
All data in The One Agents is partitioned by org_id. Every Cosmos DB container uses /org_id as the partition key. There is no cross-org data access at the database level — queries that omit org_id are rejected at the application layer.
System agents have org_id: "system" and are read-only. They are visible to all organizations but cannot be modified by any org.
Agent Execution Permissions
When an agent executes a Product Action step, it does so using a service-level integration key — not the permissions of any individual user. This has important implications:
What this means:
- Agents can take actions that no individual technician has performed directly
- The action is logged as originating from the agent, not a user
- Product API rate limits apply to the agent service key, not to individual users
What this does not mean:
- Agents are not privileged beyond what the integration key permits
- Integration keys are org-scoped — agents cannot take actions in another organization
- High-impact product actions (device isolation, data deletion) require explicit configuration and are not available by default
System agents are configured to use conservative, additive actions (create tickets, add notes, send notifications). They do not take destructive or high-impact actions without explicit human approval via an Approval Gate.
System Agent Protections
System agents are protected at multiple levels:
- Read-only: The Agents API returns
403 Forbiddenfor any attempt to update or delete a system agent - Cannot be deleted: System agents persist even if your subscription lapses — they resume when the subscription is restored
- Can be paused: Any org can pause a system agent for their organization without affecting other orgs
- Can be overridden: A custom agent with
conflict_behavior: "override_system"will suppress the system agent for matching events in that org - Audit logged: System agent executions are logged identically to custom agent executions — full step trace, credit usage, and timing
Audit Logging
Every agent execution generates an immutable audit log. The log includes:
| Field | Description |
|---|---|
execution_id | Unique execution identifier |
agent_id | Which agent ran |
org_id | Which organization |
trigger_event | The full Bus event that triggered execution, including the raw payload |
steps | Complete step-by-step trace: step ID, type, status, inputs, outputs, credits used, timing |
credits_used | Total credits consumed |
created_at / completed_at | Execution lifecycle timestamps |
context | Accumulated context variables at the point of each step |
For Approval Gates, the log additionally includes:
decided_by— the user ID who made the decisiondecided_at— when the decision was madedecision_note— optional note from the approver
Execution logs are retained for 90 days. Credit usage logs are retained for 365 days.
Permission Requirements
The Agents console in Hub follows your organization's role-based permission model:
| Role | What They Can Do |
|---|---|
| Admin | Create, edit, activate, pause, and delete agents. View all executions. Make approval decisions. Manage integration keys. |
| Technician | View agents and executions. Make approval decisions. Cannot create or modify agents. |
| Client | No access to the Agents console. |
Approval Gate notifications can be sent to any phone number or email address — the recipient does not need a Hub account to receive the notification. However, approval decisions submitted via the API require Hub authentication.
Deduplication
Events are deduplicated within a 5-minute rolling window per agent. If the same Bus event triggers the same agent twice within that window, the second execution is suppressed and a deduplication log entry is created. This prevents:
- Duplicate tickets from rapid-fire event loops
- Double-charging credits for the same event processed twice
- Conflicting Product Action steps running simultaneously on the same resource
Dedup keys are based on a combination of agent_id + event_id. Retried executions bypass deduplication — they always run regardless of the window.