Skip to content
1Claw Academy
Curriculum/Agents & Access Control2 minIntermediate · Lesson 9 of 15

Agent-to-human sharing

Let an agent hand a credential it discovered or generated back to the human who created it, without knowing their email.

Sharing usually runs human to human. The reverse direction matters for autonomous work: an agent provisions a resource, gets a credential, and needs to hand it to a person. It should not need to know who that person is.

Setting recipient_type to "creator" solves this. The API resolves the recipient from the agent's own created_by field: no email, no user ID, nothing the agent could get wrong or leak.

Watch out

Requires: an agent with write access to a vault, from the earlier lessons in this track.

Concept

recipient_type accepts user, agent, external_email, anyone_with_link, or creator. Only creator resolves the recipient from the agent's own created_by field.

  1. 1

    As the agent, share the secret back to its creator. Shares are addressed by secret ID, and expires_at is required.

    bash
    curl -s -X POST https://api.1claw.co/v1/secrets/$SECRET_ID/share \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "creator",
    "permissions": ["read"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'
  2. 2

    As the human, list what is waiting in the Inbound tab.

    bash
    1claw share list --inbound
  3. 3

    Accept it. Until you do, the share is pending and grants nothing.

    bash
    1claw share accept <share-id>
Tip

This is the clean pattern for agents that generate credentials: the agent creates the value, shares it to its creator, and the human accepts. The agent never needs directory access or an email address.

Decide

An agent provisions a database and needs to hand the generated password to the human who created it. A developer proposes having the agent look up that human's email from the org directory and share to it.

What is wrong with the proposal?

Check your understanding

2 questions
1

Why use recipient_type "creator" instead of the human's email?

2

What happens to a share before the human accepts it?