# Cyphrex documentation

Full text of the public docs. One section per page.

-----

HTML: https://cyphrex.io/docs
Markdown: https://cyphrex.io/docs/quickstart.md

OpenAPI: [/openapi.json](/openapi.json) and [/.well-known/openapi.json](/.well-known/openapi.json). For agents: [/llms.txt](/llms.txt) and [/llms-full.txt](/llms-full.txt).

# Developer Documentation

Build secure AI agents with Cyphrex. Cryptographically verified identity. Real-time enforcement. Verifiable audit trails.

SDK, API, MCP, concepts, and guides are separate pages so a fetch of this URL stays small: [SDK](/docs/sdk), [API](/docs/api), [MCP](/docs/mcp), [concepts](/docs/concepts), [guides](/docs/guides). To connect Cursor, Claude, or ChatGPT, use [Use Cyphrex with your AI](/docs/ai).

## Create an account {#create-an-account}

There is no open sign-up. Pay from the Estimated Bill on [/plans](/plans), or start a free 2-week trial with the form on that page. The form emails a login link. The 14 days start when you open the link. The trial ends with a day-14 risk report. A card is not required for the trial. Existing users log in at [/login](/login) with the method they already use: password, Google, or GitHub. After the account is ready you complete a short company profile, then land in the dashboard.

## Quick Start {#quick-start}

### Installation

Install the Cyphrex SDK for JavaScript/TypeScript or Python:

```bash
# JavaScript / TypeScript
npm install cyphrex

# Python
pip install cyphrex
```

### Get your API key

An API key is created when the account is ready: after payment, or when you open the trial login link. It is shown once in a dialog. Copy it before you dismiss the dialog. After that the dashboard shows only the last 4 characters.

If you dismiss the dialog, rotate the key: sign in at the [dashboard](/dashboard) (logged-out visits go to `/login?next=` and return you here), go to **API Keys**, and click **Rotate API key**. Rotation is owner-only (account admin). The new key is shown once. Members cannot rotate. There is no generate button.

### Register your first agent

In the dashboard, go to **Agents** → **New Agent**. Give it a name and optional behavior profile. Copy the **Agent ID**.

### Make your first check() call

Before your agent performs an action (for example an HTTP request or LLM call), call the SDK. The SDK `actionType` argument is sent on the wire as `action.type`. Do not POST a top-level `actionType` field. The API rejects that body.

```javascript
// JavaScript
const { Cyphrex } = require('cyphrex');
const cyphrex = new Cyphrex({
  apiKey: process.env.CYPHREX_API_KEY,
  agentId: 'your-agent-uuid'
});

const result = await cyphrex.check({
  actionType: 'http_call',
  url: 'https://api.example.com/data',
  payload: { method: 'GET' }
});

if (!result.allowed) {
  console.error('Blocked:', result.reason, result.severity);
  return;
}
// Proceed with the action
```

### View results in the audit log

Go to **Audit Log** in the dashboard to see every check: allowed or blocked, action type, spend, and timestamps.

### See a blocked action

A new agent starts with an empty allowlist. An empty allowlist does not block URLs, so the quick-start call above is allowed. To see a block, set **Allowed APIs** to one host and call `check()` with a different URL, or send a payload that contains a known prompt-injection phrase such as "ignore previous instructions". The response is `allowed: false` with a `reason`. Filter the audit log to **Blocked**.

### Signed receipt

A signed, verifiable receipt is a compliance evidence package. On the free trial, one package is sealed automatically when the trial ends: the day-14 risk report. It appears on **Reports**. Paid and design-partner accounts generate packages from **Reports** → **Generate Signed Report** (JSON). Check the package at [/verify](/verify) or with the verification steps on the [API](/docs/api) page.

### Team Access {#team-access}

Invite teammates to your Cyphrex account from **Settings → Team**. Invited members share the same agents, reports, and audit log.

**Roles:**

- **Admin** — full access including billing, settings, and team management
- **Member** — can view and generate reports and manage agents
- **Viewer** — read only

Invites are sent by email and expire in 48 hours. The link opens login. The person needs an account already, from paid checkout or the free trial, then accepts and completes their own profile on your company account.

-----

HTML: https://cyphrex.io/docs/ai
Markdown: https://cyphrex.io/docs/ai.md

# Use Cyphrex with your AI

The MCP server is https://mcp.cyphrex.io/mcp. Send your own API key as `Authorization: Bearer ${CYPHREX_API_KEY}`. Do not put the key in tool arguments, chat, or git.

Accounts come only from a paid plan or the free 2-week trial on [Plans](/plans). The trial ends with a day-14 risk report. There is no open sign-up.

## Cursor

Install the Cyphrex Cursor plugin from https://github.com/getcyphrex/cyphrex-cursor-plugin. Then open Plugins, Configure, and set `CYPHREX_API_KEY`. The plugin sends that value as the Bearer token.

Plain `~/.cursor/mcp.json`, if you are not using the plugin:

```json
{
  "mcpServers": {
    "cyphrex": {
      "url": "https://mcp.cyphrex.io/mcp",
      "headers": {
        "Authorization": "Bearer ${CYPHREX_API_KEY}"
      }
    }
  }
}
```

## Claude

Claude Desktop and Claude Code use the same `mcpServers` entry:

```json
{
  "mcpServers": {
    "cyphrex": {
      "url": "https://mcp.cyphrex.io/mcp",
      "headers": {
        "Authorization": "Bearer ${CYPHREX_API_KEY}"
      }
    }
  }
}
```

## ChatGPT

Add a custom MCP connector. Server URL: `https://mcp.cyphrex.io/mcp`. Header: `Authorization: Bearer ${CYPHREX_API_KEY}`.

## Tools

- `register_agent` with a name, a type, and a description. It returns a Cyphrex agent id.
- `check_action` with that agent id and an action object that has a `type`. Stop when `allowed` is not true.
- `get_audit_log` with the agent id and an optional limit.

-----

HTML: https://cyphrex.io/docs/mcp
Markdown: https://cyphrex.io/docs/mcp.md

# MCP Server {#mcp-server}

Cyphrex is a remote MCP server at https://mcp.cyphrex.io/mcp. Cursor, Claude, and ChatGPT setup is on [Use Cyphrex with your AI](/docs/ai).

Authenticate with `Authorization: Bearer ${CYPHREX_API_KEY}` on the MCP session. Do not pass the API key in tool arguments. Clients often store tool arguments in conversation history.

### Available tools

- `register_agent` — name, type, and description. Returns a Cyphrex agent id.
- `check_action` — agent id and an action. Checks it against the agent behavior profile.
- `get_audit_log` — agent id and an optional limit. Returns recent actions for that agent.

### MCP Threat Scanner {#mcp-threat-scanner}

Cyphrex scans every MCP tool call in real time and enforces policy at the point of action. When your agent connects to an MCP server through Cyphrex, the gateway checks:

- **Tool description scanning** detects prompt injection attempts embedded in tool descriptions and names. Poisoned tool lists are not returned to the agent when severity meets the agent `gateway_block_severity` (default `high`).
- **Tool poisoning detection** diffs tool schemas against stored snapshots. A changed definition at or above the block threshold is withheld from the caller.
- **Server URL validation** checks MCP server URLs against your agent behavior profile allowed domains. Unauthorized servers are blocked before `tools/call` is forwarded, and logged.
- **Tool result scanning** is post execution detection of PII patterns, prompt injection in response content, and unexpected data volumes. It cannot prevent the upstream call. Findings are logged as detection, not as a block.

Per agent settings on the behavior profile: `gateway_block_severity` (default `high`) and `gateway_fail_mode` (default `closed`; a scanner error blocks rather than forwarding).

To use the gateway, route MCP tool calls through:

```text
POST https://mcp.cyphrex.io/mcp/gateway
{
  agentId: your-agent-id,
  upstreamUrl: https://your-mcp-server.com/mcp,
  message: { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }
}
```

The response includes `outcome: "blocked"` or `"forwarded"`. Blocked requests have `upstream: null`. Threats are logged in the dashboard under **Security → MCP Threats** with severity levels, tool names, and server URLs.

### MCP Gateway {#mcp-gateway}

Route an agent's MCP `tools/call` and `tools/list` traffic through Cyphrex so policy is enforced at the point of action. On `tools/call` the order is:

1. Policy check via the Cyphrex check endpoint, using action type `tool_use`
2. Upstream server validation
3. Forward, only if both pass
4. Result scan (post execution detection, not prevention)

A block returns a JSON-RPC error with `upstream: null`. The upstream request is never made. The response includes `blockSource`: `policy` when the check endpoint denied the action, or `threat` when server validation or tool poisoning stopped it.

Two settings on the agent behavior profile control gateway behavior:

- `gateway_block_severity` defaults to `high`. Threats at this severity and above are blocked.
- `gateway_fail_mode` defaults to `closed`. Fail closed means a scanner error blocks rather than forwarding. A scanner that cannot run is not evidence that the request is safe. Set `open` only if you want a scanner error to forward with a warning.

Coverage: routing through `tool_use` means the gateway evaluates off limits actions, rate limits, freeze, and prompt injection, but not `allowed_apis` or `blocked_apis`, which apply only to `http_call`, nor `data_scopes`, which apply only to `data_access`. MCP server URL policy is enforced separately by server validation.

### Registry

Listed in the official MCP registry as `io.github.getcyphrex/cyphrex-mcp`.

Source: [github.com/getcyphrex/cyphrex-mcp](https://github.com/getcyphrex/cyphrex-mcp).

-----

HTML: https://cyphrex.io/docs/concepts
Markdown: https://cyphrex.io/docs/concepts.md

# Core Concepts {#core-concepts}

### Agent Identity

Agents are identities you register in Cyphrex. Each agent has a unique ID and optional name. All checks are attributed to an agent so you can enforce policies and track usage per agent.

### Blockchain SSN {#blockchain-ssn}

Every agent can optionally receive a **blockchain Social Security Number** — a cryptographically verified on-chain identity on Solana. It anchors your agent for enterprises that need proof of registration and auditability, not just logs.

- **Immutable identity** — A program-derived address (PDA) acts as the agent's permanent SSN on-chain.
- **Cryptographic verification** — Buyers and auditors can verify identity and registration status (see `GET /v1/verify/:ssn`).
- **Self-custody model**
  - **Self-custody** — You own the identity on all plans. Cyphrex never holds private keys.
  - **Gas policy:** Gas is covered for every agent.
- **Action attribution** — Cyphrex ties checks and audit events to the on-chain identity. Heavier on-chain aggregation can be Merkle-batched over time for cost efficiency where applicable.

**Blockchain SSN is optional.** All monitoring, enforcement, audit log, and alert features work without it. Use it when you need cryptographic audit trails, enterprise verification, and a clear identity layer for autonomous systems.

### Behavior Profiles

Behavior profiles define what an agent is allowed to do: which URLs it can call, which action types are permitted, rate limits, and spend caps. You attach a profile to an agent when registering or updating it.

### Safety Packages

Pre-built profiles for common use cases:

- **Finance** — Restricted URLs, high audit retention
- **Healthcare** — PHI-safe defaults, strict access
- **Support** — Ticket systems, knowledge bases
- **Research** — Academic APIs, read-heavy
- **Code** — Repos, CI/CD, no production writes by default
- **Custom** — Define your own rules

### Action Types

Every check includes an action type. Supported types include:

- `http_call` — Outbound HTTP/API requests
- `llm_response` — LLM completions
- `db_query` — Database queries
- `file_access` — File read/write
- `tool_use` — Tool or function calls
- Custom types for your framework

### Audit Logs

Cyphrex records each check: agent, action type, URL (if applicable), result (allowed or blocked), violations, spend, and timestamp. Retention is 30 days from each event on the free trial. Paid and design-partner accounts choose 1, 3, or 7 years.

### Alerts

Alerts are triggered when violations occur or thresholds are exceeded. Severity levels: **P1** (critical), **P2** (warning), **P3** (info). Delivery via email and/or webhook. View violations under **Alerts**. Configure destinations under **Settings → Alert notifications**.

### Signed Compliance Reports

Every compliance report exported from Cyphrex is hashed with SHA-256 over RFC 8785 JSON Canonicalization Scheme (JCS) bytes, Ed25519 signed by `cyphrex-signer-prod-01`, and independently verifiable against the public key PEM at [cyphrex.io/api/keys/cyphrex-signer-prod-01](https://cyphrex.io/api/keys/cyphrex-signer-prod-01) (text/plain). The HTML registry page is [cyphrex.io/keys/cyphrex-signer-prod-01](https://cyphrex.io/keys/cyphrex-signer-prod-01).

Supported frameworks: **SOC 2 (TSC 2017)**, **EU AI Act (Regulation (EU) 2024/1689 as amended by Regulation (EU) 2026/1744)**, **HIPAA**, **SR 11-7 (superseded by SR 26-2, April 2026)**, **SR 26-2**, **NYDFS Part 500**, **Cal. Civ. Code § 1714.46 (AB 316, Stats. 2025, ch. 672)**, **ABA Model Rules 1.1/1.6/5.1/5.3 (Formal Opinion 512)**, **Court AI Disclosure (22 NYCRR Part 161; FRCP 11(b))**, **eDiscovery TAR (FRCP 26 and 34; Sedona Principles 2 and 6)**, **ISO 42001**, **HHS OCR Phase 3**, **EU AI Act Annex III**, **FINRA Rule 4511**, **SOX 302 and 906**, **AML and FinCEN**, **NAIC Model Bulletin**, **NAIC examination handbooks (2025)**, **EU Solvency II (Directive 2009/138/EC)**, **UK FCA operational resilience (PS21/3, SYSC 15A)**, **Colorado ADMT Law (SB 26-189, effective 1 January 2027)**, **HIPAA BAA evidence (45 CFR § 164.502(e) and § 164.504(e))**, **CMS-0057-F prior authorization**, **HIPAA Security Rule NPRM (6 January 2025, not a final rule)**, **SEC Rule 17a-4**, **OCC Bulletin 2023-17**, **U.S. Treasury FS AI RMF (voluntary, 19 February 2026)**, **DORA (Regulation (EU) 2022/2554)**, **PCAOB AS 1105 and AS 1215**. The cyber insurance agent registry is underwriter evidence and asserts no legal requirement. Each agent action maps to a cited control, article, or standard with a status of **Satisfied**, **Prevented**, or **Gap, review required**. Mapping is not certification.

The free trial ends with a day-14 risk report. Signed compliance reports are included on paid and design-partner accounts. Reports are downloadable as PDF or JSON from the dashboard (**Reports**) or via the export API endpoint.

### Vertical Compliance Reports {#vertical-compliance-reports}

Compliance reports are scoped to your industry vertical, selected during onboarding.

- **Legal**: ABA Model Rules 1.1, 1.6, 5.1, 5.3 with Formal Opinion 512 (2024). Court AI Disclosure under 22 NYCRR Part 161 and FRCP 11(b). eDiscovery TAR under FRCP 26 and 34 and Sedona Principles 2 and 6. Cal. Civ. Code § 1714.46 (AB 316). ISO 42001 control mapping.
- **Healthcare**: HIPAA PHI access documentation. HHS OCR audit-ready risk assessment packages. Business associate agreement evidence under 45 CFR § 164.502(e) and § 164.504(e). The evidence record is not the contract. CMS-0057-F prior authorization decision audit trails: decision timeframes and a specific denial reason have compliance dates beginning 1 January 2026, and the Prior Authorization API begins 1 January 2027. The rule does not apply to drugs. HIPAA Security Rule NPRM of 6 January 2025 (90 FR 898): proposed encryption, MFA, real-time monitoring, and removal of addressable versus required. That NPRM is not a final rule. EU AI Act Annex III high-risk system documentation from 2 December 2027.
- **Finance**: SR 26-2 superseded SR 11-7 in April 2026; both remain mapped. FINRA Rule 4511 auditable records. SOX 302 and 906 financial close audit trails. NYDFS Part 500 compliance reports. AML and FinCEN decision audit trails. SEC Rule 17a-4(f)(2)(i)(A) audit-trail records (effective 3 January 2023; mapping is not a finding that every condition of Rule 17a-4(f) is met). OCC Bulletin 2023-17 call-chain documentation (interagency guidance, not a binding law). U.S. Treasury FS AI RMF function mapping (voluntary reference released 19 February 2026, not a regulation). DORA, Regulation (EU) 2022/2554, applicable from 17 January 2025. PCAOB AS 1105 and AS 1215 audit-evidence documentation (technology-assisted analysis amendments apply to fiscal years beginning on or after 15 December 2025; not an audit opinion).
- **Insurance**: NAIC Model Bulletin per-agent underwriting documentation. The NAIC adoption map of 8 October 2026 lists 27 states, DC, and Puerto Rico; a bulletin is guidance, not legislation. State examination documentation under the 2025 Market Regulation Handbook and Financial Condition Examiners Handbook, which are examination methodology and not a uniform statute. EU Solvency II, Directive 2009/138/EC Articles 41, 44(2)(e) and 49; Directive (EU) 2025/2 applies from 30 January 2027. UK FCA PS21/3 and SYSC 15A, with the 31 March 2025 transition ended. Colorado ADMT Law (SB 26-189, effective 1 January 2027). NYDFS Part 500. Cyber insurance agent registry for underwriters, with no legal requirement asserted.

Select your industry during onboarding to unlock vertical-specific reports in the dashboard.

### Merkle Anchoring

Daily anchoring is included on paid accounts. Hourly, every 5 minutes, and real-time are options. Each batch hashes a closed leaf per event into a Merkle tree and writes the root on-chain, giving you:

- A Merkle root of that hour's leaf set, on chain
- Per-event proof of inclusion in that on-chain root

An inclusion proof shows a closed leaf was in the tree whose root was anchored. It does not prove completeness. Cyphrex chooses the leaf set. It does not cover event fields outside the closed leaf.

Daily anchoring is included. Hourly is $150 a month. Every 5 minutes is $750 a month. Real-time is $750 a month plus $25 per 1,000 on-chain authorizations.

-----

HTML: https://cyphrex.io/docs/sdk
Markdown: https://cyphrex.io/docs/sdk.md

# SDK Reference {#sdk-reference}

Official clients are published as `cyphrex` on npm and as `cyphrex` on PyPI. There is no public SDK repository. Do not invent a GitHub package name or a scoped npm name such as `@cyphrex/sdk`.

The SDK is a thin wrapper around `POST /v1/check`. Constructor `apiUrl` defaults to `https://cyphrexapi-production.up.railway.app`. The SDK sends both auth headers and maps `actionType` / `action_type` to the HTTP field `action.type`.

### JavaScript / TypeScript

**Installation & setup**

```bash
npm install cyphrex
```

**Initialize**

```javascript
const { Cyphrex } = require('cyphrex');
const cyphrex = new Cyphrex({
  apiKey: process.env.CYPHREX_API_KEY,
  agentId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
});
```

**Check an action**

```javascript
const result = await cyphrex.check({
  actionType: 'http_call',
  url: 'https://api.example.com/endpoint',
  payload: { method: 'POST', body: { ... } }
});
```

**Response format**

The HTTP API returns `{ "allowed": true }` or `{ "allowed": false, "reason": "...", "severity": "P2" }`. The SDK copies those fields. On some error statuses it also sets `violations` to an array of string codes (for example `unauthorized`). It does not return `violations` as objects, and it does not return `spend` from the API.

```javascript
{
  allowed: true | false,
  reason?: string,
  severity?: string
}
```

### Python

**Installation & setup**

```bash
pip install cyphrex
```

**Initialize**

```python
from cyphrex import Cyphrex

cyphrex = Cyphrex(
    api_key=os.environ["CYPHREX_API_KEY"],
    agent_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
)
```

**Check an action**

```python
result = cyphrex.check(
    action_type="http_call",
    url="https://api.example.com/endpoint",
    payload={"method": "POST", "body": {...}}
)
```

**Response format**

Same HTTP fields: `result["allowed"]`, `result.get("reason")`, `result.get("severity")`.

-----

HTML: https://cyphrex.io/docs/api
Markdown: https://cyphrex.io/docs/api.md

# API Reference {#api-reference}

Official SDKs are `cyphrex` on npm and `cyphrex` on PyPI. There is no public source repository. `getcyphrex/cyphrex-sdk`, `getcyphrex/node-sdk`, and `getcyphrex/python-sdk` do not exist. Do not invent a GitHub clone URL or a scoped name such as `@cyphrex/sdk`. Machine-readable spec: [/openapi.json](/openapi.json) and [/llms.txt](/llms.txt). Integration endpoint: `POST /v1/check`.

### Base URL

Production API:

```text
https://cyphrexapi-production.up.railway.app
```

Same routes are also proxied from the site as `https://cyphrex.io/api/v1/...`. There is no `api.cyphrex.io`.

### Authentication {#authentication}

Three schemes share the `Authorization` header name. Use the scheme that matches the route. Mixing them returns 401.

**1. API key** — enforcement and MCP HTTP routes. Primary header first:

```text
x-cyphrex-key: ${CYPHREX_API_KEY}
```

Also accepted:

```text
Authorization: Bearer ${CYPHREX_API_KEY}
```

The official SDKs send both. `x-cyphrex-key` is checked first. This is not a dashboard session token.

**2. Session JWT** — dashboard routes. After login, `Authorization: Bearer <Supabase session JWT>`. An API key in this header on a dashboard route is not a valid session and will 401.

**3. MCP session** — remote MCP at `https://mcp.cyphrex.io/mcp` uses `Authorization: Bearer ${CYPHREX_API_KEY}` (your API key) on the MCP connection, not a JWT. Tools: `register_agent`, `check_action`, and `get_audit_log`. Setup: [Use Cyphrex with your AI](/docs/ai).

### API key routes

These accept `x-cyphrex-key` or `Authorization: Bearer ${CYPHREX_API_KEY}`.

**POST /v1/check** — Check an action before execution. This is the integration endpoint.

Required JSON body: `agentId` (UUID) and nested `action.type`. A top-level `actionType` is rejected with 400.

```text
POST /v1/check
Content-Type: application/json
x-cyphrex-key: ${CYPHREX_API_KEY}

{
  "agentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "action": {
    "type": "http_call",
    "url": "https://api.example.com/data",
    "payload": { "method": "GET" }
  }
}
```

Optional on `action`: `url`, `payload`, `metadata`, `dataScope` (for `data_access`), `estimatedCost`, `tool_name` / `toolName`.

Success (200):

```json
{ "allowed": true }
```

Expired free trial (still 200). Enforcement is paused, the action is recorded, and nothing is blocked:

```json
{ "allowed": true, "enforcement": "off", "reason": "trial_expired", "code": "trial_expired" }
```

The trial recorded-action cap is 100,000. Actions after that cap are still stored, including after day 14. The count shown to a trial account, in the dashboard and on `GET /v1/billing/usage`, stays at 100,000 until the account is paid. A paid account is shown the true count. The check does not return `recorded: false`.

Policy deny (still 200):

```json
{ "allowed": false, "reason": "URL not in allowed list", "severity": "P2" }
```

Some deny paths also include `violation_type` (for example `rate_limit_exceeded`, `off_limits_action`, `unsafe_output`). The API does not return a `violations` object array or a `spend` object on this route.

Other statuses: 400 missing or invalid body; 401 bad or missing key; 402 enforced-action cap while the trial is active (25,000 enforced actions). The 100,000 recorded-action cap does not return 402 and does not stop storage. After day 14, checks are HTTP 200, blocking stops, and actions keep being recorded. 403 frozen agent; 404 unknown or inactive agent; 429 request rate limit (paid accounts are not blocked or throttled for volume; overage is billed); 503 auth, write, or deadline failure (fail-closed: `allowed: false`).

**POST /v1/mcp/...** — HTTP helpers behind the hosted MCP server. Same API key auth as `/v1/check`. Prefer `https://mcp.cyphrex.io/mcp`. The tools are `register_agent`, `check_action`, and `get_audit_log`.

### Public routes (no authentication)

- `GET /v1/keys/:keyId` — signing public key PEM (`text/plain`)
- `GET /v1/keys` — published key registry JSON
- `GET /v1/verify/:ssn` — public blockchain SSN lookup
- `POST /v1/inclusion/verify` — Merkle inclusion check
- `GET /v1/reports/:id/public` — opted-in signed report JSON
- `GET /v1/reports/by-pdf-sha256/:sha256` — report JSON bound to a PDF hash
- `POST /v1/solana/verify` — confirm a Solana tx references a report hash

### Dashboard routes (session JWT)

These require `Authorization: Bearer <session JWT>` from `POST /v1/auth/login`. They do not accept the API key. There is no `GET /v1/audit` and no `POST /v1/behavior-profiles`.

**POST /v1/agents** — Create an agent. Body: `name` (required), optional `type` (or `agent_type`), `purpose`, `version`. Returns the agent row. A behavior profile is created empty. There is no `behaviorProfileId` field.

**GET /v1/events** — Audit log. Query: `agentId`, `from`, `to`, `limit`, `offset`. Returns `{ events, total, limit, offset }`.

**PATCH /v1/agents/:id/profile** — Update the agent behavior profile. Body may include `allowed_apis`, `blocked_apis`, `spending_limit`, `freeze_on_violation`.

**POST /v1/agents/:id/apply-package** — Copy a safety package's rules onto that agent's behavior profile.

**GET /v1/alerts** — Violation inbox (blocked events). Returns violations since last acknowledge. Configure destinations via **GET/POST /v1/alert-configs**. **GET /v1/alerts/open-count** drives the sidebar badge. **POST /v1/alerts/acknowledge** clears open count.

**GET /v1/alert-configs** — Notification destinations (email, webhook).

**POST /v1/events/export-signed** — Generate a signed compliance evidence package.

**Requires:** a paid or design-partner account. A free trial ends with one day-14 risk report, sealed automatically.

Request body: `agentIds` (array of UUID strings, optional — all agents if empty), `format` (`"json"` | `"pdf"`), `frameworks` (non-empty string[]: `"soc2"`, `"euaiact"`, `"hipaa"`, `"sr11-7"`, `"sr26-2"`, `"nydfs"`), `from` (ISO timestamp), `to` (ISO timestamp). The singular `framework` field is no longer accepted.

Returns a signed compliance evidence package (schemaVersion `1.0.0`) containing:

- sha256 hash of RFC 8785 JCS canonical report bytes (`canonicalization: "rfc8785-jcs"`)
- Ed25519 signature (verify against `GET /v1/keys/:keyId`)
- blockchain SSN and anchor history (if the agent is registered)
- `inclusionProofs`: per-event proof of inclusion in the on-chain root when that event was in an hourly tree. Unanchored events (current hour, or hours with no stored path) are `{ eventId, anchored: false }` only. Membership of a closed leaf, not completeness.
- per-event `controls` from stored mappings filtered to requested frameworks
- status per action: Satisfied, Prevented, or Gap, review required
- PDF binary or JSON object depending on `format`

#### Verifying a signed JSON report (v1.0.0)

The signed payload is tagged `canonicalization: "rfc8785-jcs"`. That is RFC 8785 JSON Canonicalization Scheme: lexicographic object-key order, the RFC's number format (so `1e-7` not `1e-07`), and unescaped Unicode in strings. Sorted-key `JSON.stringify` / Python `json.dumps` are not JCS and will not verify.

The `timestamp` object (including `issued_at`, `anchor`, `anchor_tx_signature`, `anchor_block_height`, and `message`) is part of the signed payload. Strip only the top-level verification fields (`sha256`, `signature`, `algorithm`, `publicKeyUrl`) before canonicalizing. Keep `canonicalization` inside the signed core.

Use a JCS library in the language you verify from. Node: npm `canonicalize` (erdtman). Python: PyPI `rfc8785`. Verify the Ed25519 signature over the UTF-8 JCS bytes first, then SHA-256 those same bytes and compare to `report.sha256`. Do not stop at the hash: an attacker who tampers a field can recompute `sha256`.

Node.js

```javascript
// schemaVersion 1.0.0 — RFC 8785 JSON Canonicalization Scheme (JCS).
// report.canonicalization === "rfc8785-jcs"
// npm install canonicalize@2

const canonicalize = require('canonicalize');
const { createHash, verify, createPublicKey } = require('crypto');

const STRIP = new Set(["sha256", "signature", "algorithm", "publicKeyUrl"]);
const core = Object.fromEntries(Object.entries(report).filter(([k]) => !STRIP.has(k)));
if (core.canonicalization !== "rfc8785-jcs") {
  throw new Error(`Unsupported canonicalization: ${core.canonicalization}`);
}

const canonical = canonicalize(core);

const publicKey = createPublicKey(publicKeyPem);
const isValid = verify(
  null,
  Buffer.from(canonical, 'utf8'),
  publicKey,
  Buffer.from(report.signature, 'base64')
);
if (!isValid) throw new Error("Invalid signature");

const computedHash = createHash('sha256').update(canonical, 'utf8').digest('hex');
if (computedHash !== report.sha256) throw new Error('Hash mismatch');
console.log('Valid signature');
```

Python (JCS library + cryptography only. No Cyphrex code)

This snippet checks the Ed25519 signature. It does not walk the Merkle path.

```python
# pip install rfc8785 cryptography
# report.canonicalization == "rfc8785-jcs"
# Fetch the PEM (this is text/plain). https://cyphrex.io/keys/<keyId> is HTML.
# curl -fsS -o cyphrex-public.pem https://cyphrex.io/api/keys/cyphrex-signer-prod-01
import base64, hashlib, json
import rfc8785
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.serialization import load_pem_public_key

STRIP = ("sha256", "signature", "algorithm", "publicKeyUrl")

report = json.loads(open("cyphrex-report.json", encoding="utf-8").read())
pem = open("cyphrex-public.pem", "rb").read()
if report.get("canonicalization") != "rfc8785-jcs":
    raise SystemExit("Unsupported canonicalization: " + str(report.get("canonicalization")))

core = {k: v for k, v in report.items() if k not in STRIP}
canonical = rfc8785.dumps(core)
if isinstance(canonical, str):
    canonical = canonical.encode("utf-8")

# Check order: Ed25519 first (always), then SHA-256 of the same JCS bytes.
# Recomputing sha256 after a tamper does not make a forged package verify.
key = load_pem_public_key(pem)
try:
    key.verify(base64.b64decode(report["signature"]), canonical)
except InvalidSignature:
    raise SystemExit("Invalid signature")

digest = hashlib.sha256(canonical).hexdigest()
if digest != report["sha256"]:
    raise SystemExit("Hash mismatch")
print("Valid signature")
```

### Independent inclusion check {#independent-inclusion-check}

The public verifier on [/verify](/verify) runs inclusion and the on-chain root in the browser. This Python verifier is the independent copy of those two checks. No account. It picks the first anchored event and prints the index.

Download [verify_inclusion_independent.py](/tools/verify_inclusion_independent.py). Allowed imports: rfc8785, cryptography, hashlib, stdlib. Raw PEM: [/api/keys/cyphrex-signer-prod-01](/api/keys/cyphrex-signer-prod-01). Public packages: `GET /v1/reports/:id/public` for the sample IDs on [/verify](/verify).

#### Setup

```bash
pip install rfc8785 cryptography
curl -fsS -o verify_inclusion_independent.py https://cyphrex.io/tools/verify_inclusion_independent.py
curl -fsS -o cyphrex-public.pem https://cyphrex.io/api/keys/cyphrex-signer-prod-01
curl -fsS -o report.json https://cyphrexapi-production.up.railway.app/v1/reports/8d539bd4-cc20-434f-9b10-093392dd3981/public
curl -fsS -o other.json https://cyphrexapi-production.up.railway.app/v1/reports/2c696df7-83e9-41d1-b08c-3692bad5f005/public
```

The first run should pass. The next three should each fail. That is the demonstration.

#### Run

```bash
python3 verify_inclusion_independent.py report.json cyphrex-public.pem
python3 verify_inclusion_independent.py report.json cyphrex-public.pem --tamper-event-url https://evil.example
python3 verify_inclusion_independent.py report.json cyphrex-public.pem --foreign-proof other.json
python3 verify_inclusion_independent.py report.json cyphrex-public.pem --reorder-sibling
```

**POST /v1/inclusion/verify** — Public inclusion check.

No authentication required. Body is a whole package (`{ package }` or `{ report }`) or a single `{ event, proof }`. Recomputes the closed-leaf hash, walks the path, and searches the named Solana transaction for the claimed root. That is membership in the anchored tree, not completeness.

**GET /v1/keys/:keyId** — Public key registry.

No authentication required. Returns the Ed25519 public key PEM for a given signing key ID as `text/plain`.

Example: `GET /v1/keys/cyphrex-signer-prod-01`

Fetch the PEM from [cyphrex.io/api/keys/cyphrex-signer-prod-01](https://cyphrex.io/api/keys/cyphrex-signer-prod-01) or `GET /v1/keys/cyphrex-signer-prod-01` on the API. The HTML registry page at [cyphrex.io/keys/cyphrex-signer-prod-01](https://cyphrex.io/keys/cyphrex-signer-prod-01) is documentation, not the key.

**GET /v1/agents/:id/anchors** — Merkle anchor history. Session JWT, not the API key.

Returns on-chain Merkle anchors for an agent you own:

- `merkle_root`
- `event_ids` included in the batch
- `solana_tx_signature`
- `solana_block_height`
- `anchored_at` timestamp

Anchoring on paid accounts: daily is included. Hourly is $150 a month. Every 5 minutes is $750 a month. Real-time is that $750 plus $25 per 1,000 on-chain authorizations.

### Blockchain SSN API {#blockchain-endpoints}

Registration and transaction-payload routes use **dashboard authentication**: `Authorization: Bearer <session JWT>` (same token as the web app after login), not the API key. `GET /v1/verify/:ssn` is public and takes no credentials.

**POST /v1/agents/:id/register-blockchain-self-custody**

Register with **self-custody**. Available on **all plans**.

**GET /v1/agents/:id/registration-tx** returns a transaction payload for the user wallet to sign and submit.

Request body (JSON):

```json
{
  "walletAddress": "<solana-pubkey>",
  "transactionSignature": "<signed-tx-from-user-wallet>"
}
```

The API verifies the Solana transaction signature and stores `blockchain_ssn`, `wallet_address`, and `solana_tx_signature`.

**GET /v1/verify/:ssn** — Public verification.

No authentication. Verifies an agent by its blockchain SSN (on-chain and Cyphrex metadata).

**Response** (200, example fields):

```json
{
  "verified": true,
  "agent_type": "support",
  "registered_at": "<iso-timestamp>",
  "created_at": "<iso-timestamp>",
  "action_count": 42,
  "status": "Active",
  "owner_wallet": "<pubkey-or-null>"
}
```

`status` reflects on-chain state when available (for example Active). **404** if the SSN is unknown.

-----

HTML: https://cyphrex.io/docs/guides
Markdown: https://cyphrex.io/docs/guides.md

# Integration Guides {#integration-guides}

### LangChain

Wrap your chain with a Cyphrex check before calling the LLM or tools. Use a custom callback or middleware that invokes `cyphrex.check()` with `actionType: 'llm_response'` or `'tool_use'` and the relevant payload.

### CrewAI

Add a pre-step to each task that calls Cyphrex with the task type and target (for example a URL or tool name). Block task execution if `result.allowed === false`.

### OpenAI Assistants

Use the Assistants API run lifecycle: before executing a tool call or message, call `cyphrex.check()` with the tool name and arguments. Cancel the run if the check fails.

### AutoGPT

Integrate in the action execution layer: before running any command or API call, pass the action to Cyphrex. Only proceed when `allowed` is true.

### Custom agent frameworks

Call `check()` at the point where your agent is about to perform an action. Map your internal action types to Cyphrex `actionType` and include `url` and `payload` as needed. Enforce `allowed` before proceeding.

## Security Best Practices {#security-best-practices}

### What Cyphrex stores

Cyphrex records action metadata: agent, action type, URL, result, violation details, spend and timestamp. Action payloads are not retained by default. The payload field is evaluated in memory for prompt injection and policy matching, then discarded. Payload retention can be enabled per agent for debugging, in which case up to 2048 characters are stored for the duration of your log retention window. Structured violation summaries generated by Cyphrex are always retained, as they contain no caller-supplied content.

### API key security

API keys are shown once at generation or rotation and never again. The dashboard displays only the last 4 characters. Store your key immediately in a secrets manager or environment variable. If you lose it, rotate from **API Keys** in the dashboard.

Never expose keys client-side. Keys must only be used in server-side or backend environments. Never commit them to version control.

Rotate keys regularly. Revoke compromised keys immediately from the dashboard.

### Behavior profiles

Set the minimum required permissions for each agent. Restrict URLs to known domains. Restrict action types to what the agent actually needs. Never use a wildcard allowlist in production.

### Monitor and alert

Configure P1 alerts for critical violations. Review the audit log weekly for unexpected patterns. Use the **MCP Threats** page to monitor tool call security.

### Team access

Use the **Viewer** role for anyone who only needs to read reports. Use **Member** for engineers who need to manage agents. Reserve **Admin** for founders and leads only.

### Platform security

Cyphrex enforces rate limiting on all auth endpoints. Login attempts are limited to 5 per 15 minutes per IP. All API responses use security headers including `Strict-Transport-Security`, `X-Content-Type-Options`, and `X-Frame-Options`. All resource access is account-scoped. Team members can only access resources belonging to their company account.

## Plans and limits {#pricing-limits}

### Plan comparison

| Plan | Price | Agents | Enforced actions | Log retention | Blockchain SSN | Gas covered | Merkle anchoring | Signed reports | Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Free trial | $0, 14 days | One | 25,000 enforced and 100,000 recorded | 30 days | Optional, self-custody | Yes | Not included | Day-14 risk report | No priority |
| Paid | Usage rates, $1,000 a month minimum | Unlimited | The volume you buy | 1, 3, or 7 years | Optional, self-custody | Yes | Daily included. Hourly, every 5 minutes, and real-time are options | Included | Standard. A priority support add-on has a 4-hour response |
| Design partner | Sign by Oct 31: 3 months free, then year one at 40% off action usage ($800 a month floor), yearly prepay, price locked 24 months | Unlimited | The volume you buy, at the design partner rate | 1, 3, or 7 years | Optional, self-custody | Yes | Daily included. Hourly, every 5 minutes, and real-time are options | Included | High |

Paid accounts buy usage. The first framework pack is included. Extra packs, a named DPA, and a signed BAA are add-ons on the [plans](/plans) page. Design partners use the same usage quote at the offer above. You agree to let us measure your action counts.

### Rate limits

Paid usage is not blocked or throttled for volume. You are warned at 75, 80, 90, and 100 percent of what you bought. See the dashboard for current usage.

### Overage

Usage above what you bought is billed through Stripe at the overage rate for the band your purchase ends in. Yearly prepays give a monthly allowance, and that overage is billed monthly. While a free trial is active, enforcement stops at 25,000 actions. The shown recorded count pauses at 100,000, and actions are still stored.

### Moving between plans

Paid checkout starts from the Estimated Bill. See [Plans](/plans).

## Incident Response {#incident-response}

### What constitutes a security incident

Any unauthorized access to customer agent data, audit logs, compliance reports, API keys, or behavior profiles. Any breach of Cyphrex platform infrastructure.

### Detection

Sentry monitors all API errors and exceptions in real time. Railway provides infrastructure-level alerting. Supabase provides database access logs.

### Response timeframes

- Detection to internal assessment: 1 hour
- Customer notification of confirmed breach: within 24 hours
- HIPAA-covered customers: written notification within 48 hours
- Full incident report to affected customers: within 7 days of resolution

### Notification

Affected customers are notified directly by email to the account owner from hello@cyphrex.io with a description of what was accessed, when, what was done to contain it, and what remediation steps were taken.

### Containment steps

- Immediately revoke all affected API keys
- Rotate affected infrastructure credentials
- Isolate affected accounts
- Preserve all logs for forensic analysis
- Patch the vulnerability before restoring service

### Subprocessors

Supabase (database and auth), Railway (compute), Resend (email), Sentry (error monitoring), Solana (blockchain anchoring). Each maintains their own security programs and incident response procedures.

### Contact

Report security issues to hello@cyphrex.io. Platform status at [status.cyphrex.io](https://status.cyphrex.io).

## Platform Security {#security}

### Infrastructure

Cyphrex runs on Railway (compute) and Supabase (database and auth). All data is stored in the United States. Tenant isolation is enforced in the API layer: every route is account-scoped and ownership is checked before any resource is returned. Row-level security policies are additionally enabled on customer tables.

### Authentication

Existing users log in with email and password, Google, or GitHub. There is no open sign-up. New accounts come from paid checkout on the plans page, or from the free 2-week trial form, which emails a login link. The 14 days start when that link is opened. Passwords are handled by Supabase Auth and are never stored by Cyphrex in plaintext. JWT tokens use the ES256 algorithm. Tokens presenting insecure algorithms such as alg: none are rejected at the API layer.

### API keys

API keys are hashed with SHA-256 before storage. The plaintext key is shown once at generation and never again. Comparison uses constant-time equality to prevent timing attacks. Keys can be rotated at any time from the dashboard by an account admin.

### Rate limiting

All auth endpoints are rate limited. Login attempts are capped at 5 per 15 minutes per IP. API key rotation is capped at 3 per hour per account. Global API rate limiting applies to all routes.

### Transport security

All traffic is served over HTTPS with HSTS enabled. Security headers including X-Frame-Options, X-Content-Type-Options, Content-Security-Policy, and Referrer-Policy are set on all responses.

### Data isolation

Every API route enforces account-scoped access. Team members can only access resources belonging to their company account. Administrative actions including API key rotation, billing and team management are restricted to account admins.

### Status

Platform uptime is monitored and published at [status.cyphrex.io](https://status.cyphrex.io).