# 1Claw — AI Agent Secrets Management

> HSM-backed secret management for AI agents and humans. Zero-knowledge vault with envelope encryption, agent-native access control, customer-managed encryption keys (CMEK), Intents API for transaction signing, and x402 micropayments.

## Links

- Preferred citation URL: https://1claw.xyz
- Website: https://1claw.xyz
- API: https://api.1claw.xyz
- Docs: https://docs.1claw.xyz
- MCP Server: https://mcp.1claw.xyz
- Shroud (TEE proxy): https://shroud.1claw.xyz
- Dashboard: https://1claw.xyz (login required)
- GitHub: https://github.com/1clawAI/1claw
- npm SDK: https://www.npmjs.com/package/@1claw/sdk
- npm CLI: https://www.npmjs.com/package/@1claw/cli
- npm MCP: https://www.npmjs.com/package/@1claw/mcp
- npm OpenAPI Spec: https://www.npmjs.com/package/@1claw/openapi-spec
- Contact: ops@1claw.xyz

## Contact

- Email: ops@1claw.xyz
- Support: https://1claw.xyz/status (system status), https://t.me/+jG4Rm7XHJ79mNDRh (community)

## What 1Claw Does

1Claw stores and manages secrets (API keys, tokens, certificates, private keys, environment variables) in HSM-backed encrypted vaults. AI agents are first-class principals — they authenticate with scoped API keys, receive short-lived JWTs, and access only the secret paths explicitly granted by a human via policies.

## Architecture

- **Vault API** (Rust/Axum) at api.1claw.xyz — RESTful API with JWT Bearer auth, HSM-backed signing
- **Shroud** (Rust) at shroud.1claw.xyz — TEE-protected LLM proxy + transaction signing (GKE, AMD SEV-SNP)
- **Dashboard** (Next.js) at 1claw.xyz — Web UI for humans, includes setup wizards
- **MCP Server** (TypeScript) at mcp.1claw.xyz — Model Context Protocol for AI agents
- **SDK** (@1claw/sdk) — TypeScript client library
- **CLI** (@1claw/cli) — Command-line tool for CI/CD and DevOps

Both `api.1claw.xyz` and `shroud.1claw.xyz` serve the full Intents API. Shroud adds TEE-grade key isolation, LLM traffic inspection (secret redaction, PII scrubbing, prompt injection defense), and intent validation for transactions.

## Authentication

- **Human users**: Email/password, Google OAuth, or personal API keys (`1ck_` prefix)
- **AI agents**: Three auth methods — API key (`ocv_` prefix, default), mTLS (client certificate), or OIDC Client Credentials. API key agents exchange credentials for short-lived JWT via `POST /v1/auth/agent-token`. Supports key-only auth: agents can provide just `api_key` (without `agent_id`) and the server resolves the agent from a stored key prefix.
- **MFA**: Optional TOTP 2FA for human logins (Pro tier and above)
- **API keys**: `1ck_` keys work as Bearer tokens on all authenticated endpoints

## Core Concepts

### Vaults
Isolated containers for secrets. Each vault has its own HSM key encryption key (KEK). Secrets within a vault are envelope-encrypted: per-secret data encryption keys (DEKs) wrapped by the vault KEK.

### Secrets
Key-value pairs stored in vaults, addressed by path (e.g., `api-keys/stripe`). Supports types: generic, password, api_key, certificate, private_key, ssh_key, env. Secrets are versioned. Optional metadata, expiry, and max access count.

### Agents
AI agent identities registered via the dashboard or API. Agents support three authentication methods: `api_key` (default, generates `ocv_` prefixed key), `mtls` (client certificate fingerprint), and `oidc_client_credentials` (OIDC issuer + client ID). All agents automatically receive an Ed25519 SSH keypair stored in a dedicated `__agent-keys` vault for future encrypted A2A messaging. Agents can be scoped to specific vaults (`vault_ids`), specific secret paths (via policies), and have a custom token TTL (`token_ttl_seconds`). Agents cannot access anything not explicitly granted by a human.

### Agent Self-Enrollment
Agents can register themselves with zero credentials via `POST /v1/agents/enroll` (public endpoint). The agent provides its name and the email of a human with a 1Claw account. The API creates the agent and emails credentials to the human. Available via SDK (`AgentsResource.enroll()`), CLI (`1claw agent enroll`), and raw HTTP. Rate limited: 1 per email per 10 minutes + IP rate limiting. Zero access by default until the human creates policies.

### Agent-to-Human Sharing
Agents can share secrets back with the human who created them using `recipient_type: "creator"`. No email or user ID needed — the API resolves it from the agent's `created_by` field. The human sees the share in their Inbound tab and accepts it. This enables a pattern where agents autonomously discover/generate credentials and report them to their human.

### Policies
Access control rules that bind a principal (agent or user) to a set of secret paths in a vault. Policies specify path patterns (glob), permissions (read/write), optional conditions (IP ranges, time windows), and expiry.

### Customer-Managed Encryption Keys (CMEK)
Enterprise opt-in feature. The human generates a 256-bit AES key in the dashboard (WebCrypto). The key never leaves their device — only its SHA-256 fingerprint is stored on the server. Secrets are encrypted client-side before upload. Server-assisted rotation re-encrypts all secrets in batches of 100 with progress tracking.

### Intents API
Agents can sign and broadcast EVM transactions without seeing private keys. Keys stay in the HSM. Per-agent guardrails: allowed chains, recipient allowlists, per-tx value caps, daily spending limits. Supports EIP-155 legacy and EIP-1559 Type 2 transactions. Optional Tenderly simulation before signing. Replay protection via `Idempotency-Key` header (UUID, 24h TTL; auto-generated by SDK and MCP). Server-side nonce serialization with an atomic `nonce_tracker` table (`SELECT FOR UPDATE`) prevents nonce collisions across concurrent agents. `GET .../transactions/{tx_id}` redacts `signed_tx` by default; pass `?include_signed_tx=true` to include it.

### Sharing
Secrets can be shared between users and agents via links (with optional passphrase and IP restrictions), direct user/agent shares, email invites (humans only), or "share back to creator" for agents. Inbound shares require explicit accept/decline.

### Shroud (TEE Proxy)
Rust service running inside Google Cloud Confidential GKE (AMD SEV-SNP). Sits between AI agents and LLM providers, performing real-time security inspection of all traffic. Supports OpenAI, Anthropic, Google Gemini, Mistral, and Cohere. Inspection pipeline: hidden content stripping, secret redaction (Aho-Corasick matching against vault manifest), PII detection, context injection defense, prompt injection detection, token counting, policy enforcement, and response credential scanning. Also handles transaction signing with keys that never leave the TEE.

Per-agent configuration: each agent has `shroud_enabled` (boolean) and `shroud_config` (JSON) fields. Config options: `pii_policy` (block/redact/warn/allow), `injection_threshold` (0.0–1.0), `context_injection_threshold`, `allowed_providers`, `allowed_models`, `denied_models`, `max_tokens_per_request`, `max_requests_per_minute`, `max_requests_per_day`, `daily_budget_usd`, `enable_secret_redaction`, `enable_response_filtering`. Configure via dashboard (Agent → Shroud LLM Proxy card), API (`PUT /v1/agents/{id}`), SDK, or CLI (`1claw agent update <id> --shroud true`).

## API (OpenAPI 3.1)

Base URL: `https://api.1claw.xyz`

Key endpoints:
- `POST /v1/auth/token` — Login
- `DELETE /v1/auth/token` — Revoke current Bearer token (returns 200; reused token then returns 401)
- `POST /v1/auth/agent-token` — Agent token exchange (accepts `api_key` alone or `agent_id` + `api_key`; returns `agent_id` and `vault_ids` for auto-discovery)
- `GET/POST /v1/vaults` — List/create vaults
- `GET/DELETE /v1/vaults/{id}` — Get/delete vault
- `POST/DELETE /v1/vaults/{id}/cmek` — Enable/disable CMEK
- `POST /v1/vaults/{id}/cmek-rotate` — Start CMEK rotation
- `GET/PUT/DELETE /v1/vaults/{id}/secrets/{path}` — CRUD secrets
- `GET/POST /v1/agents` — List/create agents
- `POST /v1/agents/enroll` — Agent self-enrollment (public, no auth, emails credentials to human)
- `GET /v1/agents/me` — Agent self-profile (includes created_by)
- `GET/PATCH/DELETE /v1/agents/{id}` — Get/update/delete agent
- `POST /v1/agents/{id}/rotate-identity-keys` — Rotate agent SSH/ECDH keys (user-only)
- `POST /v1/agents/{id}/transactions` — Submit transaction (over quota: 0.25% of tx value, 402 if unpaid)
- `POST /v1/agents/{id}/transactions/simulate` — Simulate transaction
- `GET/POST /v1/vaults/{id}/policies` — List/create policies
- `POST /v1/secrets/{id}/share` — Share a secret (agents use recipient_type: "creator" to share with their human)
- `GET /v1/audit/events` — Query audit log
- `GET /v1/billing/subscription` — Billing status
- `GET /v1/chains` — Supported blockchains

Full spec: https://www.npmjs.com/package/@1claw/openapi-spec

**API limits and security:** Request body size is limited to 5MB (413 if exceeded). Public auth routes (e.g. login, signup) are rate-limited (5 req burst, 1/sec); 429 when exceeded. Revoked tokens (via `DELETE /v1/auth/token`) are rejected with 401. Share creation: 10/min/org.

## Agent Onboarding Flows

### Human registers agent (dashboard)
1. Dashboard wizard at /agents/wizard — 3 steps: register agent, save credentials, connection snippets
2. Or full form at /agents/new with auth method, scopes, guardrails, vault binding

### Agent self-enrolls (API/CLI/SDK)
1. `POST /v1/agents/enroll` with `{ name, human_email }` — no auth needed
2. `npx @1claw/cli agent enroll my-agent --email alice@example.com`
3. `AgentsResource.enroll("https://api.1claw.xyz", { name, human_email })`
4. Human receives credentials by email, creates policies in dashboard
5. Agent exchanges API key for JWT, reads/writes secrets, shares back to human

### MCP configuration (single credential)
```json
{
  "mcpServers": {
    "1claw": {
      "command": "npx",
      "args": ["-y", "@1claw/mcp"],
      "env": {
        "ONECLAW_AGENT_API_KEY": "<agent-api-key>"
      }
    }
  }
}
```

Only `ONECLAW_AGENT_API_KEY` is required. Agent ID and vault are auto-discovered from the token exchange response. Optional overrides: `ONECLAW_AGENT_ID` (explicit agent), `ONECLAW_VAULT_ID` (explicit vault), `ONECLAW_BASE_URL` (default: https://api.1claw.xyz).

Note: Key-only auth requires agents created or key-rotated after the prefix feature was deployed. Older agents should provide `ONECLAW_AGENT_ID` or rotate their key.

## Fleet Management

For operating dozens or hundreds of agents:
- Batch provisioning via SDK or CLI (`agent create` in a loop)
- Self-enrollment at scale (stagger requests to respect 10-min per-email cooldown)
- Shared vaults with path-scoped policies, or per-agent vaults for isolation
- Vault binding (`vault_ids`) as a second layer of access control
- Transaction guardrails for all Intents API agents
- Audit log filtering by agent ID for monitoring

## Billing

- Free: 1,000 req/mo, 3 vaults, 50 secrets, 2 agents
- Pro ($29/mo): 25,000 req/mo, 25 vaults, 500 secrets, 10 agents
- Business ($149/mo): 100,000 req/mo, 100 vaults, 5,000 secrets, 50 agents, CMEK
- Enterprise: Custom, unlimited, KMS delegation, BAA

Overage: prepaid credits or x402 on-chain micropayments on Base. x402 and credit prices are tier-based (see overage_cost_cents). Intents API submit when over quota: 0.25% of transaction value (USD), no cap; config ONECLAW_ETH_USD_PRICE (default 2500). 402 response (spec-compliant for x402scan): x402Version, accepts[] with maxAmountRequired (atomic), resource (full URL), payTo, asset, maxTimeoutSeconds, mimeType; unauthenticated paid routes return 402 so scanners can discover. Client pays and retries with X-PAYMENT.

## MCP Tools (for AI agents)

The MCP server at mcp.1claw.xyz provides these tools:
- list_secrets, get_secret, put_secret, delete_secret, describe_secret
- rotate_and_store, get_env_bundle
- create_vault, list_vaults, grant_access, share_secret
- simulate_transaction, submit_transaction
- inspect_content — standalone security scanner: detects prompt injection, command injection, social engineering, PII, encoding tricks, and Unicode obfuscation in arbitrary text. Returns a verdict (clean/warning/suspicious/malicious) with detailed threat breakdown.

Configure in Claude Desktop, Cursor, or any MCP-compatible client. Only `ONECLAW_AGENT_API_KEY` is required — agent ID and vault are auto-discovered.

### Local-only mode (no account needed)

Set `ONECLAW_LOCAL_ONLY=true` to run the MCP server with only the `inspect_content` tool — no vault credentials required. Ideal for users running local models (Ollama, LM Studio, llama.cpp) who want prompt injection and threat detection without a 1claw account.

```json
{
  "mcpServers": {
    "1claw": {
      "command": "npx",
      "args": ["-y", "@1claw/mcp"],
      "env": {
        "ONECLAW_LOCAL_ONLY": "true"
      }
    }
  }
}
```