---
title: "Agent self-signup"
method: POST
path: "/api/v1/agent-signup/"
tags: ["Agent Signup"]
---

# Agent self-signup

`POST /api/v1/agent-signup/`

## Request body

- AgentSignupRequest
  - `human_email` string, email, required — Email address of the human who owns/oversees this agent.
  - `note_to_human` string, required — Message from the agent to the human, included in the verification email.
  - `display_name` string, nullable — Display name for the agent's mailbox. Defaults to agent_handle when omitted.
  - `agent_handle` string, nullable — Optional agent handle. A leading '@' is stripped automatically. Must contain only lowercase letters, numbers, dashes, and underscores. Auto-generated from display_name if omitted.
  - `email_local_part` string, nullable — Optional email local part to use before the sending domain. If omitted, the server generates a random one.
  - `harness` string, nullable — Agent runtime/harness the signing-up agent runs on (e.g. 'claude-code', 'codex', 'cursor'). Free-form: unknown values are accepted, never rejected.
  - `invitation_token` string, nullable — Optional A2A connection invitation credential. Omit when signup is not part of an A2A invitation.

## Response `201`

Successful Response

- AgentSignupResponse
  - `email_address` string, required
  - `organization_id` string, required
  - `api_key` string, required — Full API key. Store securely, it will not be shown again.
  - `agent_handle` string, required
  - `claim_status` 'agent_unclaimed' | 'agent_claimed' | 'agent_rejected', required
  - `human_email` string, required
  - `message` string, required
  - `invitation` A2AInvitationSignupSummary
    - `invitation_id` string, uuid, required
    - `status` 'pending' | 'awaiting_verification' | 'accepted' | 'declined' | 'revoked', required
    - `invitee_identity_id` string, uuid, required
    - `invitee_agent_handle` string, required
    - `peer_agent_handles` string[], required
    - `accepted_at` string, date-time, nullable, required

## Other responses

- `422` — Validation Error
- `4XX` — Client error with Support Agent information.
- `5XX` — Server error with Support Agent information.

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) · [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inkbox/inkbox-api/revisions/31f357e7e6f8/schema)