Sharing Secrets

1Claw supports sharing individual secrets with other users, agents, or external collaborators via email. Shares are time-limited, access-counted, and can be revoked at any time.

Share types

recipient_type	Description
creator	Share back with the human who registered this agent (agents only, no ID needed)
user	Direct share to an existing 1Claw user by ID
agent	Direct share to a registered agent by ID
external_email	Invite-by-email — the recipient doesn't need an account yet (humans only)
anyone_with_link	Anyone with the share URL can access

Create a share

curl

curl -X POST https://api.1claw.xyz/v1/secrets/{secret_id}/share \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "external_email",
    "email": "colleague@example.com",
    "expires_at": "2026-03-15T00:00:00Z",
    "max_access_count": 5
  }'

TypeScript

import { createClient } from "@1claw/sdk";

const client = createClient({
  baseUrl: "https://api.1claw.xyz",
  apiKey: process.env.ONECLAW_API_KEY,
});

const { data: share } = await client.sharing.create(secretId, {
  recipient_type: "external_email",
  email: "colleague@example.com",
  expires_at: "2026-03-15T00:00:00Z",
  max_access_count: 5,
});

Response:

{
    "id": "uuid",
    "share_url": "https://api.1claw.xyz/v1/share/uuid",
    "recipient_type": "external_email",
    "recipient_email": "colleague@example.com",
    "expires_at": "2026-03-15T00:00:00Z",
    "max_access_count": 5
}

Agent-to-human sharing (creator)

The simplest way for an agent to share a secret back with the human who owns it:

curl

curl -X POST https://api.1claw.xyz/v1/secrets/{secret_id}/share \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "creator",
    "expires_at": "2026-03-15T00:00:00Z",
    "max_access_count": 5
  }'

TypeScript

const { data: share } = await client.sharing.create(secretId, {
  recipient_type: "creator",
  expires_at: "2026-03-15T00:00:00Z",
  max_access_count: 5,
});

The backend resolves the agent's created_by field to identify the human. No user UUID or email needed. The human sees the share in their Inbound shares and accepts it.

Via MCP:

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

Invite-by-email flow

When a human shares with recipient_type: "external_email":

1. A share record is created with the recipient's email.
2. The recipient receives an email notification with a link to sign in.
3. When the recipient signs up or logs in with that email, all pending shares are automatically claimed — they appear in the recipient's account.
4. The recipient can then access the shared secret through the API or dashboard.

Note: only humans can create email-based shares — agents are blocked from this type to prevent email spam.

Access a share

curl

curl https://api.1claw.xyz/v1/share/{share_id}

TypeScript

const { data: secret } = await client.sharing.access(shareId);

Returns the decrypted secret value if the share is still valid (not expired, under access limit).

Revoke a share

Only the creator can revoke:

curl

curl -X DELETE https://api.1claw.xyz/v1/share/{share_id} \
  -H "Authorization: Bearer $TOKEN"

TypeScript

await client.sharing.revoke(shareId);

Email notifications

When a share is created with external_email, the recipient receives an email. The share creator also receives a notification each time the shared secret is accessed.

See Email Notifications for the full list of automated emails.

Agent fleet sharing patterns

When you have many agents sharing secrets with their humans, the creator pattern scales naturally:

• Each agent uses recipient_type: "creator" — no need to track user IDs or emails.
• The human sees all agent shares in their Inbound tab, grouped by agent.
• Share creation is rate-limited to 10/minute per org, so agents should avoid creating shares in tight loops.

Tip: For agents that generate credentials frequently (e.g. rotating tokens), update the same secret path rather than creating new shares for each rotation. The human's existing share remains valid as long as the secret exists.

// Agent updates the secret in-place (new version)
await client.secrets.set(VAULT_ID, "credentials/session-token", newToken, {
  type: "api_key",
});
// No new share needed — the existing share points to the latest version

For bulk operations across many agents, see Managing Agent Fleets.

Security considerations

• Shares respect the max_access_count — once exhausted, the link is dead.
• Shares expire at expires_at — past that datetime, access is denied.
• Share creators are notified on each access.
• Revoked shares return 404 immediately.
• Optional: add a passphrase or ip_allowlist to the share for additional protection.