1claw

# 1Claw — HSM-Backed Secret Management for AI Agents 1Claw is a cloud HSM-backed secrets manager. Agents access API keys, passwords, and credentials at runtime without them ever entering the conversation context. Secrets are encrypted with keys that never leave the HSM. **API base URL:** `https://api.1claw.xyz` **MCP endpoint:** `https://mcp.1claw.xyz/mcp` **Dashboard:** `https://1claw.xyz` **Docs:** `https://docs.1claw.xyz` ## When to use this skill - You need an API key, password, or credential to complete a task - You want to store a newly generated credential securely - You need to share a secret with a user or another agent - You need to rotate a credential after regenerating it - You want to check what secrets are available before using one - You need to sign or simulate an EVM transaction without exposing private keys --- ## Setup ### Option 1: MCP server (recommended for AI agents) Add to your MCP client configuration. The server auto-refreshes JWT tokens. ```json { "mcpServers": { "1claw": { "command": "npx", "args": ["-y", "@1claw/mcp"], "env": { "ONECLAW_AGENT_ID": "<agent-uuid>", "ONECLAW_AGENT_API_KEY": "<agent-api-key>", "ONECLAW_VAULT_ID": "<vault-uuid>" } } } } ``` Hosted HTTP streaming mode: ``` URL: https://mcp.1claw.xyz/mcp Headers: Authorization: Bearer <agent-jwt> X-Vault-ID: <vault-uuid> ``` ### Option 2: TypeScript SDK ```bash npm install @1claw/sdk ``` ```ts import { createClient } from "@1claw/sdk"; const client = createClient({ baseUrl: "https://api.1claw.xyz", agentId: process.env.ONECLAW_AGENT_ID, apiKey: process.env.ONECLAW_AGENT_API_KEY, }); ``` ### Option 3: Direct REST API Authenticate, then pass the Bearer token on every request. ```bash # Exchange agent credentials for a JWT TOKEN=$(curl -s -X POST https://api.1claw.xyz/v1/auth/agent-token \ -H "Content-Type: application/json" \ -d '{"agent_id":"<uuid>","api_key":"<key>"}' | jq -r .access_token) # Use the JWT curl -H "Authorization: Bearer $TOKEN" https://api.1claw.xyz/v1/vaults ``` **Alternative:** `1ck_` API keys (personal or agent) can be used directly as Bearer tokens — no JWT exchange needed. --- ## Authentication ### Agent auth flow 1. Human registers an agent in the dashboard or via `POST /v1/agents` with an `auth_method` (`api_key` default, `mtls`, or `oidc_client_credentials`). For `api_key` agents → receives `agent_id` + `api_key` (prefix `ocv_`). For mTLS/OIDC agents → receives `agent_id` only (no API key). 2. All agents auto-receive an Ed25519 SSH keypair (public key on agent record, private key in `__agent-keys` vault). 3. API key agents exchange credentials: `POST /v1/auth/agent-token` with `{ "agent_id": "<uuid>", "api_key": "<key>" }` → returns `{ "access_token": "<jwt>", "token_type": "bearer", "expires_in": 3600 }`. 4. Agent uses `Authorization: Bearer <jwt>` on all subsequent requests. 5. JWT scopes derive from the agent's access policies (path patterns). If no policies exist, scopes are empty (zero access). The agent's `vault_ids` are also included in the JWT — requests to unlisted vaults are rejected. 6. Token TTL defaults to ~1 hour but can be set per-agent via `token_ttl_seconds`. The MCP server auto-refreshes 60s before expiry. ### API key auth Tokens starting with `1ck_` (human personal API keys) or `ocv_` (agent API keys) can be used as Bearer tokens directly on any authenticated endpoint. --- ## MCP Tools Reference ### list_secrets List all secrets in the vault. Returns paths, types, and versions — never values. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `prefix` | string | no | Path prefix to filter (e.g. `api-keys/`) | ### get_secret Fetch the decrypted value of a secret. Use immediately before the API call that needs it. Never store the value or include it in summaries. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `path` | string | yes | Secret path (e.g. `api-keys/stripe`) | ### put_secret Store a new secret or update an existing one. Each call creates a new version. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `path` | string | yes | | Secret path | | `value` | string | yes | | The secret value | | `type` | string | no | `api_key` | One of: `api_key`, `password`, `private_key`, `certificate`, `file`, `note`, `ssh_key`, `env_bundle` | | `metadata` | object | no | | Arbitrary JSON metadata | | `expires_at` | string | no | | ISO 8601 expiry datetime | | `max_access_count` | number | no | | Max reads before auto-expiry (0 = unlimited) | ### delete_secret Soft-delete a secret. Reversible by an admin. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `path` | string | yes | Secret path to delete | ### describe_secret Get metadata (type, version, expiry) without fetching the value. Use to check existence. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `path` | string | yes | Secret path | ### rotate_and_store Store a new value for an existing secret, creating a new version. Use after regenerating a key. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `path` | string | yes | Secret path | | `value` | string | yes | New secret value | ### get_env_bundle Fetch an `env_bundle` secret and parse its `KEY=VALUE` lines as JSON. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `path` | string | yes | Path to an `env_bundle` secret | ### create_vault Create a new vault for organizing secrets. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | yes | Vault name (1–255 chars) | | `description` | string | no | Short description | ### list_vaults List all vaults accessible to you. No parameters. ### grant_access Grant a user or agent access to a vault path pattern. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `vault_id` | string (UUID) | yes | | Vault ID | | `principal_type` | `user` \| `agent` | yes | | Who to grant access to | | `principal_id` | string (UUID) | yes | | The user or agent UUID | | `permissions` | string[] | no | `["read"]` | `["read"]`, `["write"]`, or `["read","write"]` | | `secret_path_pattern` | string | no | `**` | Glob pattern for secret paths | ### share_secret Share a secret via link, with your creator, or with a specific user/agent. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `secret_id` | string (UUID) | yes | The secret's UUID | | `recipient_type` | `user` \| `agent` \| `anyone_with_link` \| `creator` | yes | `creator` shares with the human who registered this agent — no ID needed | | `recipient_id` | string (UUID) | conditional | Required for `user` and `agent` types | | `expires_at` | string | yes | ISO 8601 expiry | | `max_access_count` | number | no (default 5) | Max reads (0 = unlimited) | Targeted shares (creator/user/agent) require the recipient to explicitly accept before access. ### simulate_transaction Simulate an EVM transaction via Tenderly without signing. Returns balance changes, gas estimates, success/revert status. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `to` | string | yes | | Destination address (0x-prefixed) | | `value` | string | yes | | Value in ETH (e.g. `"0.01"`) | | `chain` | string | yes | | Chain name or chain ID (see Supported Chains) | | `data` | string | no | | Hex-encoded calldata | | `signing_key_path` | string | no | `keys/{chain}-signer` | Vault path to signing key | | `gas_limit` | number | no | 21000 | Gas limit | ### submit_transaction Submit an EVM transaction for signing and optional broadcast. Requires `crypto_proxy_enabled`. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `to` | string | yes | | Destination address | | `value` | string | yes | | Value in ETH | | `chain` | string | yes | | Chain name or chain ID | | `data` | string | no | | Hex-encoded calldata | | `signing_key_path` | string | no | `keys/{chain}-signer` | Vault path to signing key | | `nonce` | number | no | auto-resolved | Transaction nonce | | `gas_price` | string | no | | Gas price in wei (legacy mode) | | `gas_limit` | number | no | 21000 | Gas limit | | `max_fee_per_gas` | string | no | | EIP-1559 max fee in wei (triggers Type 2) | | `max_priority_fee_per_gas` | string | no | | EIP-1559 priority fee in wei | | `simulate_first` | boolean | no | true | Run Tenderly simulation before signing | ---