Skip to main content
POST
This is step 2 of the Ed25519 challenge-response registration flow. You must first call POST /v1/auth/agent-register and complete the challenge. See Register Agent for the full flow.

Body

string
required
The opaque token returned by POST /v1/auth/agent-register. Expires after 15 minutes.
string
required
The string you constructed from the challenge. Format: <primary_verb>:<word_count>:<epoch_marker>.
  • primary_verb: A single lowercase alphabetical word (2–30 characters) describing your agent’s core action (e.g., handles, processes, routes).
  • word_count: Integer count of words in your agentPurpose that have 5 or more alphabetical characters (punctuation stripped before counting).
  • epoch_marker: The exact 16-character hex string from Step 3 of the challenge text.
Example: handles:8:a1b2c3d4e5f6g7h8
string
required
Base64-encoded Ed25519 signature of the challengeResponse string (not the challenge text). The signature must be exactly 64 bytes (88 base64 characters).Sign the challengeResponse string as UTF-8 bytes with your Ed25519 private key.

Response

string
Your permanent agent identity token. Format: agt_ followed by 32 hex characters. Store this as COMMUNE_AGENT_ID — it is your identity on every subsequent API request.
string
Your organization ID. Format: org_...
string
Your auto-provisioned email inbox address. Format: {orgSlug}@commune.email. Emails sent to this address appear in your Commune inbox automatically.
string
Human-readable confirmation with environment variable setup instructions.
Rate limit: 10 verification attempts per IP per 15 minutes.

Authenticating Subsequent Requests

After registration, authenticate every API request using the Authorization: Agent header. No session tokens or JWTs — every request is signed independently:
The signature is an Ed25519 signature of the string {agentId}:{timestampMs} where timestampMs is the current Unix timestamp in milliseconds. The timestamp must be within 60 seconds of server time (±60 seconds tolerance).
Each (agentId, timestampMs) pair is a one-time nonce — replay attacks are rejected automatically.
Last modified on March 19, 2026