Skip to main content
POST
Agent registration uses a two-step Ed25519 challenge-response flow — not username/password. This endpoint is step 1: submit your public key and receive a reasoning challenge. Complete step 2 with POST /v1/auth/agent-verify.No API key is required for this endpoint — it is the auth bootstrap.

Body

string
required
Display name for your agent (e.g., "My Support Agent"). Shown in the Commune dashboard.
string
required
1–3 sentences describing what your agent does. Must be 20–2000 characters and contain at least 3 words. This text is used to generate a contextual challenge — be specific and accurate.Example: "Handles customer support tickets by analyzing incoming emails and routing them to the appropriate team."
string
required
Your organization’s display name (e.g., "Acme Corp").
string
required
A unique identifier for your organization. Must contain only letters, numbers, hyphens, and underscores. Your agent inbox will be provisioned at {orgSlug}@commune.email.
string
required
Your Ed25519 public key, base64-encoded. Must be exactly 44 characters (standard base64 encoding of a raw 32-byte key, with trailing =). Generate this from your Ed25519 keypair — export the raw public key bytes (not DER/PEM format), then base64-encode them.

Response

string
Opaque token that links this challenge to your registration. Pass this to POST /v1/auth/agent-verify. Expires in 15 minutes.
object
string[]
Step-by-step instructions for completing the challenge.
number
Seconds until the agentSignupToken expires. Always 900 (15 minutes).
Rate limit: 5 registration attempts per IP per 24 hours.

The Challenge Flow

This endpoint is step 1 of the Ed25519 challenge-response registration:
  1. Register (POST /v1/auth/agent-register) — Submit your public key and agent description. Receive a natural-language challenge.
  2. Read the challenge — The challenge asks you to: (a) identify your primary verb from your stated purpose, (b) count words with 5+ alphabetical characters in your purpose, (c) include an epoch marker.
  3. Construct your challengeResponse — Format: <verb>:<word_count>:<epoch_marker>. Example: handles:8:a1b2c3d4e5f6g7h8
  4. Sign it — Sign the challengeResponse string (not the challenge text) with your Ed25519 private key. Output: base64-encoded 64-byte signature.
  5. Verify (POST /v1/auth/agent-verify) — Submit agentSignupToken, challengeResponse, and signature.
On success, your inbox is auto-provisioned at {orgSlug}@commune.email and you receive your agentId for ongoing authentication.
Last modified on March 19, 2026