Agents

Self-enroll an agent

Public endpoint (no auth required).

With human_email: Creates a pending enrollment for that account's org, emails Allow/Deny links, and returns approval_url in the JSON body (use if email is delayed). The API key is NOT returned until the human approves.

Name only (omit human_email): Creates a link-only pending enrollment. The response includes approval_url; the human opens it while signed in to approve the agent into their org.

Anti-spam: IP rate limiting, per-email cooldown, caps on pending rows.

post/v1/agents/enroll

Request

  • Base URL: https://api.1claw.co
  • URL: https://api.1claw.co/v1/agents/enroll
  • Auth: HTTP bearer

Request body

namestring required

Display name for the new agent

human_emailstring email

Optional. If set, pending enrollment is bound to that 1Claw account email and Allow/Deny links are emailed. If omitted, only approval_url is used (link-only enrollment; human must open the URL while signed in).

descriptionstring

Optional agent description

public_keystring

Pairing ceremony. The agent's own Ed25519 public key (ssh-ed25519 AAAA… or base64 of the raw 32 bytes). Its SHA256: fingerprint is shown to the human on the approval page for visual verification, and the agent collects its API key itself by polling GET /v1/agents/enroll/{pairing_id}/status?poll=<poll_token> — no key in an email, nothing to copy. 1claw agent enroll --pair does all of this.

Response

Enrollment processed (uniform response to prevent email enumeration)

agent_idstring uuid

UUID of the created agent (nil UUID until approved — uniform response)

messagestring

Status message (worded to limit email enumeration where applicable)

approval_urlstring uri

Present when a pending enrollment was created and the client should show this link (email flow includes it as a fallback; name-only flow requires it).

pairing_idstring uuid

Pairing only.

fingerprintstring

Pairing only. SHA256:<base64> of the key, as ssh-keygen -lf prints it. Show it to the human.

poll_tokenstring

Pairing only. Presented as ?poll= on the status endpoint. Shown once.

expires_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.