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` **Shroud (TEE proxy):** `https://shroud.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 - You want TEE-grade key isolation for transaction signing (use Shroud at `shroud.1claw.xyz`) --- ## Setup ### Option 0: Self-enrollment (new agents) If you don't have credentials yet, self-enroll — this sends them to your human: ```bash # curl curl -s -X POST https://api.1claw.xyz/v1/agents/enroll \ -H "Content-Type: application/json" \ -d '{"name":"my-agent","human_email":"human@example.com"}' # TypeScript SDK (static method, no auth needed) import { AgentsResource } from "@1claw/sdk"; await AgentsResource.enroll("https://api.1claw.xyz", { name: "my-agent", human_email: "human@example.com", }); # CLI (no auth needed) npx @1claw/cli agent enroll my-agent --email human@example.com ``` The human receives the Agent ID + API key by email. They then configure policies for your access. ### Option 1: MCP server (recommended for AI agents) Add to your MCP client configuration. Only the API key is required — agent ID and vault are auto-discovered. ```json { "mcpServers": { "1claw": { "command": "npx", "args": ["-y", "@1claw/mcp"], "env": { "ONECLAW_AGENT_API_KEY": "<agent-api-key>" } } } } ``` Optional overrides: `ONECLAW_AGENT_ID` (explicit agent), `ONECLAW_VAULT_ID` (explicit vault). 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", apiKey: process.env.ONECLAW_AGENT_API_KEY, }); ``` ### Option 3: Direct REST API Authenticate, then pass the Bearer token on every request. ```bash # Exchange agent API key for a JWT (key-only — agent_id is auto-resolved) RESP=$(curl -s -X POST https://api.1claw.xyz/v1/auth/agent-token \ -H "Content-Type: application/json" \ -d '{"api_key":"<key>"}') TOKEN=$(echo "$RESP" | jq -r .access_token) AGENT_ID=$(echo "$RESP" | jq -r .agent_id) # 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 `{ "api_key": "<key>" }` (or `{ "agent_id": "<uuid>", "api_key": "<key>" }`) → returns `{ "access_token": "<jwt>", "expires_in": 3600, "agent_id": "<uuid>", "vault_ids": ["..."] }`. Agent ID is optional — the server resolves it from the key prefix. 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 |