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

Agent self-enrollment and approvals

Let an agent enroll itself with no credentials and route the approval to a human.

This creates a new agent via self-enrollment: a different bootstrap path from Lesson 1's human-initiated registration. Sometimes the agent boots before anyone has provisioned it. The enroll endpoint is public, so an agent can request its own identity and wait for a human to approve. The API key is emailed to the human after approval and never returned to the agent.

Concept

Two enrollment methods follow. Pick one: the email path suits a human who is not at their terminal, and the approval-URL path suits one who is.

  1. 1

    Option A: Submit an enrollment with a name and a human_email. Allow and Deny links are sent to that address. No credentials are required.

    bash
    curl -s -X POST https://api.1claw.co/v1/agents/enroll \
  -H "Content-Type: application/json" \
  -d '{"name":"deploy-bot","human_email":"alice@example.com","description":"CI pipeline agent"}'
  2. 2

    Option B: Send name only. The response includes an enrollment_id and an approval_url the human opens while signed in. No email needed. Sample response: {"enrollment_id":"enr_abc123","approval_url":"https://1claw.co/approve/enr_abc123","status":"pending"}

    bash
    curl -s -X POST https://api.1claw.co/v1/agents/enroll \
  -H "Content-Type: application/json" \
  -d '{"name":"deploy-bot"}'
  3. 3

    The human approves via the emailed link or the approval_url. After approval an agent is created in their org and the ocv_ key is emailed to them.

  4. 4

    The human then writes a policy so the new agent can read the paths it needs. Follow Lesson 2 (Policies and scoped access) in this track.

Concept

For sensitive actions an agent can also file an approval with POST /v1/approvals/request, directed to its creator. Requests carry a risk tier: T1 is informational, T2 requires biometric step-up, and T3 requires passkey plus TOTP attestation before the human can approve.

Watch out

Enrollment is rate limited: one per email per 10 minutes when email is used, plus caps on pending rows and per-IP limits. Some branches return a uniform 201 to limit email enumeration.

You can now bootstrap an agent from zero credentials and hand the approval to a human, who receives the key and grants scoped access.

Decide

Self-enrollment is public: an agent posts a name and a human's email, and credentials are mailed to that human. A security reviewer flags this as an open registration endpoint and asks you to remove it.

How do you answer?

Check your understanding

3 questions
1

Where does the enrolled agent's API key go?

2

Which risk tier requires passkey plus TOTP attestation?

3

What can an agent submit with name only and no email?