Architecture

Overview

CydraLabs is a control plane between enterprise AI agents and the tools, data and systems they act on. Three products share one platform, one sign-in and one set of services for identity, policy, approval, telemetry and evidence:

Analytical work never sits on the synchronous action path. A decision depends on nothing beyond identity checks, registry lookups, inspection, the policy decision and approval verification. Risk recalculation and graph updates run after the decision is committed; evidence is written in the same transaction as the decision.

Platform layers

Policy decisions are made by a deterministic evaluator: Open Policy Agent (Rego) or an embedded evaluator with identical semantics. Both are tested against the same golden decision cases (see policy language). No decision, risk factor or evidence record is produced by a language model.

The platform is one modular application (an API and background workers) rather than a set of microservices. Module boundaries are enforced in code, which keeps the action path short and simple to audit.

People and agents

Two kinds of caller use the platform, and every API endpoint accepts exactly one of them.

People

• Sign in through the identity provider (OpenID Connect with PKCE). Multi-factor authentication is mandatory.
• Receive an opaque session cookie (__Host- prefixed, HttpOnly, never sent to other hosts) plus a CSRF token for every change. Sessions end after 30 minutes of inactivity or 12 hours at most, and can be ended on all devices.
• Are authorised by permission: each endpoint requires one named permission, granted through roles.

Agents

• Never use cookies. An administrator issues a workload identity (client ID and a secret shown once).
• Exchange it for a short-lived token: an Ed25519-signed JWT, audience cydra-gateway, valid for five minutes, carrying the organisation, agent, identity and environment.
• Suspending an agent or revoking its sessions invalidates every token issued before that moment. A suspended agent's requests are denied by policy and recorded as evidence.

Action-control workflow

An agent submits each proposed tool call to POST /api/v1/actions before anything runs, with an Idempotency-Key. The gateway then works through ten steps:

Action states

Each action request moves through a small state machine:

revoked means the agent was contained while the action was in flight. cancelled means a person cancelled it before execution.

Approval tokens

When an approval is granted, the agent fetches a compact signed token (Ed25519 JWS) from GET /api/v1/actions/gateway/{id} and resubmits the identical request with the same idempotency key. The token binds:

• the approval request, the organisation and the requesting agent;
• the delegated user (or the agent itself), the tool and operation, and the target;
• a request hash: SHA-256 of the canonical tenant, agent, tool, operation, target, parameters, environment and delegated user. Any change to the request invalidates the token;
• an expiry equal to the approval's expiry (15 minutes by default).

On resubmission the gateway verifies every binding, consumes the approval with a conditional update (so it is single-use) and evaluates policy again before executing. Requests can need one or more distinct approvers, and an approver cannot approve an action taken on their own behalf.

Tenancy

• The organisation (tenant) always comes from the authenticated session or agent token, never from a request body.
• Every organisation-owned table has PostgreSQL row-level security. Each request sets the organisation for its transaction; without it, queries return no rows. The application connects with a role that cannot bypass row-level security and owns no tables.
• Services also filter by organisation explicitly, and looking up another organisation's object returns 404, never 403, so object IDs cannot be probed.
• A plan decides which modules (Shield, Gateway, Govern) an organisation can use; permissions outside the plan are removed server-side.

Evidence chain

Each organisation has its own chain of evidence records, which can be added to but not changed. For every record:

• the payload is stored as canonical JSON (sorted keys, compact separators, UTF-8);
• sequence is gap-free per organisation, allocated under a row lock;
• payload_hash = SHA-256(payload), and record_hash = SHA-256(previous record hash + "|" + payload hash);
• signature = Ed25519(record hash), with the signing key ID.

The application role has no permission to update or delete evidence. GET /api/v1/evidence/verify recomputes the whole chain and every signature and reports any break. This is a hash-linked, signed log: tampering is detectable without any distributed ledger.

Risk score and Security Graph

The Agent Risk Score (0–100) is inherent exposure, plus an active-threat modifier, minus credit for controls in place, using a published, versioned ruleset (ars-2026.1). Bands: 0–24 Low, 25–49 Moderate, 50–74 High, 75–100 Critical. Every factor records the evidence it was based on, and a what-if calculation shows the effect of a proposed fix.

The Agent Security Graph is projected from the registry into node and edge tables with validity periods, so you can ask what was true at a point in time. Queries cover neighbours, shortest paths, transitive access (effective authority), blast radius and high-risk paths to sensitive data or privileged tools, up to eight hops.

API conventions

To try the workflow end to end, follow the quick start.

Applies to the CydraLabs proof-of-concept platform. Last updated 4 October 2026. Questions or corrections: contact us.