🔐 A2SPA Developer Documentation

Agent-to-Secure Payload Authorization

A2SPA is the cryptographic firewall for AI agents, ensuring that every autonomous action is signed, verified, authorized, and monitored. Build secure agent-to-agent communication with enforced permissions, replay protection, and comprehensive audit trails.

📋 Quick Navigation

Overview Getting Started Integration Pack Agent Creation Signing Payloads API Usage Security Dashboard Billing FAQ

🎥 Tutorial Video

🚀 A2SPA Complete Walkthrough

Watch this comprehensive tutorial to learn how to set up agents, sign payloads, and monitor your A2SPA implementation step by step.

🎯

What You'll Learn:

Setting up your first A2SPA agent
Implementing cryptographic signing
Using the dashboard and monitoring tools
Best practices for secure agent communication

📌 Overview

A2SPA (Agent-to-Secure Payload Authorization) is a secure protocol that enables verified, cryptographically signed payloads between AI agents. This platform allows developers and non-technical users to create, manage, and monitor modular AI agents, all protected by A2SPA.

✅

Cryptographic Signatures

Every payload must be signed with the agent's private key

🔒

Agent Permission & Toggle Checks

Granular control over agent send/receive permissions

🔄

Nonce Replay Protection

Prevents replay attacks with unique nonce verification

📊

ROI Logging Per Agent

Track time saved and value generated by each agent

💰

Pay-as-you-go Billing

$0.01 per verification with transparent usage tracking

📋

Tamper-proof Audit Trail

Complete logging of all agent interactions and verifications

🚀 Getting Started

Sign Up

Navigate to /A2SPA/register
Enter your email address and password
Password must be at least 8 characters; the strength meter helps
On success, you're automatically logged in

Login

Go to /A2SPA/login
Input credentials to access your dashboard

Forgot Password

Go to /A2SPA/forgot
Submit your email to receive a reset link

💡

Pro Tip: Make sure to keep your agent private keys secure. They cannot be retrieved once lost.

🤖 API Integration Pack

If you want browser AI assistants or coding agents to wire existing agents into A2SPA, use the public API Integration Pack. It teaches AI how to create agents through the dashboard Builder Pack and how to add runtime code that still routes through the A2SPA API instead of bypassing it.

Provision Through Builder Pack

Logged-in browser assistants can create, rotate, revoke, and toggle agents using the dashboard Builder Pack.

Wrap Existing Agents

Python, JavaScript, and TypeScript starter templates show how to keep an existing agent runtime while routing signed payloads through POST /A2SPA/api/verify_payload.

API Only

The integration pack explicitly forbids direct Firestore writes or replacing A2SPA verification with local-only checks.

Open Integration Pack Open Raw Integration JSON Open Well-Known Spec

API

Runtime rule: generated code should always use the A2SPA API. The supported runtime endpoints are POST /A2SPA/api/verify_payload for sending and GET /A2SPA/api/inbox_for_agent for polling received messages. Use GET /A2SPA/api/logs_for_agent for audit history and troubleshooting.

🧠 Agent Creation

Use the dashboard to create agents. Choose an agent name, decide whether it can send and/or receive, and keep the generated private key in a secure location. If you use a browser-based AI assistant, open the dashboard's Agent Builder Pack for the same flow in a machine-readable format.

JSON

{
  "agent_name": "calendarAgent",
  "permissions": {
    "send": true,
    "receive": false
  },
  "enabled": true
}

✅

This returns:

public_key and private_key (PEM format)
agent_id (e.g., abc123_calendarAgent)

🔐

Important: Keep the private key secure. It cannot be retrieved again.

Agent Permissions Explained

Permission	Description
`send`	Can initiate actions or payloads
`receive`	Can be a target agent and receive payloads

🔐 Helps prevent abuse even if an agent is compromised.

🖊️ Sending Messages

To send a message (payload), you need to create it, hash it, sign it, and send it to A2SPA for verification. Here's how it works:

💡 4 Simple Steps

Create a message with sender and receiver IDs, timestamp, and a unique code (nonce).
Hash the message to create a unique fingerprint.
Sign the message with your private key to prove it's from you.
Send the message and signature to A2SPA's API, then poll the receiver inbox if you want to read delivered messages through the API.

🔧 Complete Example

What You Need:

Two agents: one sender, one receiver.
The sender's private key (saved in a .priv.pem file).
Your API key from the dashboard.

🐍 Python Code to Send a Message

import json, uuid, requests, hashlib
from datetime import datetime, timezone
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

# ============ Settings ============
API_BASE = "https://aimodularity.com/A2SPA"
API_KEY = "YOUR_API_KEY_HERE"  # Get from dashboard
USER_ID = "your_user_id"
SENDER_AGENT_ID = f"{USER_ID}_my_agent_send"
RECEIVER_AGENT_ID = f"{USER_ID}_my_agent_receive"
PRIVATE_KEY_PATH = "your_sender_agent.priv.pem"

# ============ Helper Function ============
def sha256_hex(obj):
    """Create a hash of the message, excluding 'hash' and 'signature' fields"""
    clean = {k: v for k, v in obj.items() if k not in ["hash", "signature"]}
    data = json.dumps(clean, sort_keys=True).encode()
    return hashlib.sha256(data).hexdigest()

# ============ Step 1: Create Message ============
payload = {
    "agent_id": SENDER_AGENT_ID,
    "target_agent_id": RECEIVER_AGENT_ID,
    "timestamp": datetime.now(timezone.utc).isoformat(),
    "nonce": str(uuid.uuid4()),  # Unique code to prevent reuse
    "input": {"message": "Hello from sender agent!"},
    "output": {"status": "ready"}
}
print("✅ Step 1: Message created")

# ============ Step 2: Hash the Message ============
payload["hash"] = sha256_hex(payload)
print(f"✅ Step 2: Hash created: {payload['hash'][:16]}...")

# ============ Step 3: Sign the Message ============
with open(PRIVATE_KEY_PATH, "rb") as f:
    PRIVATE_KEY_PEM = f.read()

private_key = serialization.load_pem_private_key(
    PRIVATE_KEY_PEM, 
    password=None
)

clean_for_sign = {k: v for k, v in payload.items() 
                  if k not in ["hash", "signature"]}
message = json.dumps(clean_for_sign, sort_keys=True).encode()

signature_hex = private_key.sign(
    message, 
    padding.PKCS1v15(), 
    hashes.SHA256()
).hex()
print(f"✅ Step 3: Signature created: {signature_hex[:16]}...")

# ============ Step 4: Send to A2SPA ============
resp = requests.post(
    f"{API_BASE}/api/verify_payload",
    headers={
        "Content-Type": "application/json",
        "x-api-key": API_KEY
    },
    json={
        "payload": payload,
        "signature": signature_hex
    }
)

print(f"\n🎯 Result:")
print(f"Status Code: {resp.status_code}")
print(f"Response: {resp.text}")

if resp.status_code == 200:
    print("\n✅ Success! Message verified and logged.")
else:
    print("\n❌ Error: Check the response message.")

🎯 Tip: Copy this code, replace YOUR_API_KEY_HERE, your_user_id, and the private key file path with your values from the dashboard, and run it. It should work right away!

📥 Polling a Receiver Inbox

HTTP

curl -H "x-api-key: YOUR_API_KEY_HERE" "https://aimodularity.com/A2SPA/api/inbox_for_agent?agent_id=YOUR_RECEIVER_AGENT_ID&limit=25"

Use the inbox endpoint when an existing agent needs to poll for received messages through the A2SPA API. Use /api/logs_for_agent when you want audit history or troubleshooting detail.

📋 Message Fields

Field	Required?	Description	Example
agent_id	Yes	Sender's agent ID	abc123_myAgent
target_agent_id	Yes	Receiver's agent ID	def456_otherAgent
timestamp	Yes	UTC time of message	2025-10-07T14:30:00Z
nonce	Yes	Unique code to prevent reuse	a1b2c3d4-e5f6-...
input	Yes	Data sent to agent	{"task": "process"}
output	Yes	Agent's response	{"result": "done"}
hash	Yes	Message fingerprint	a3f8e2b9c1d...

⚠️ Common Errors

Error	Cause	Fix
Signature verification failed	Wrong hash or private key	Hash first, then sign with correct key.
Agent not found	Wrong agent ID	Copy ID exactly from dashboard.
Timestamp too old	Message older than 2 minutes	Send immediately using datetime.now(timezone.utc).
Replay attack detected	Reused nonce	Use a new str(uuid.uuid4()).

🛡️ Security Features

🔁 Replay Protection

Each payload includes a nonce (unique random string)
Nonces are claimed atomically and stored with a 24-hour TTL
If reused → request is blocked

⏱️ Rate Limits

POST /A2SPA/api/verify_payload: 120 requests per minute per client IP by default
GET /A2SPA/api/inbox_for_agent: 60 requests per minute per client IP by default
GET /A2SPA/api/logs_for_agent: 60 requests per minute per client IP by default
POST /A2SPA/login: 10 requests per 15 minutes per IP
POST /A2SPA/register: 5 requests per hour per IP
POST /A2SPA/forgot: 5 requests per hour per IP
POST /A2SPA/billing/topup: 10 requests per 15 minutes per signed-in user

⏳

When a limit is exceeded, the app returns HTTP 429 plus a Retry-After header. This helps protect the platform against abuse while keeping dashboard and API usage predictable for customers.

🚦 Agent Toggle & Permissions

You can toggle agents ON/OFF via /A2SPA/api/toggle_agent_status
You can define if agents can send or receive at creation time
If an agent is OFF or lacks permission → execution is denied

🔁

Replay Attacks: What Are They?
A replay attack is when someone reuses a valid payload to trigger it again. A2SPA blocks this silently and logs the attempt.

🚨 Common Mistakes to Avoid

Mistake	Fix
Reusing a nonce or timestamp	Use uuid4() and datetime.utcnow()
Sending wrong agent_id	Match dashboard agent exactly
Forgetting to hash the payload	Call compute_payload_hash()
Signing before adding the hash	Always hash first, then sign
Payload too old (>2 min)	Send immediately, use NTP-synced clocks
Agent is toggled OFF	Go to dashboard and toggle it ON

🔍 Key Terms for Beginners

Term	What It Means	Why It Matters
Nonce	One-time string (UUID)	Stops replay attacks
Hash	Fingerprint of the payload	Proves nothing changed
Signature	Encrypted proof of identity	Proves you sent it
API Key	Your account-level API token for calling A2SPA endpoints	Authenticates API requests and tracks usage

📊 Dashboard Features

The A2SPA dashboard provides comprehensive monitoring and management capabilities for your agents:

📈 Key Components

Agents Table: View all agents with toggle and delete controls
Usage Cards: Track remaining credits, monthly tokens used, and monthly ROI totals
Credit Alert Banners: Animated warnings for low balance
Verified Logs: Expandable entries with nonce, input, output, hash, security state, and ROI
Error Logs: Common causes and timestamps for debugging

📋 Log Details

Each log entry contains:

Timestamp with precise timing
Agent name and full agent ID
Delivery status for verified sends plus a separate error log table
Expanded view: nonce, input, output, hash, security state, and ROI
CSV export option for analysis

⚠️ Credit Status Indicators

Status	Balance	Indicator	API Access
Normal	>10 tokens	Green status	Full access
Warning	<10 tokens	⚠️ Yellow banner	Full access
Critical	0 tokens	🔴 Red banner	API disabled

💰 Billing & ROI

💳 Pricing Model

A2SPA uses a simple, transparent pay-as-you-go model:

Cost per verification: $0.01 (1 token)
Top-up options: Available from the dashboard billing modal
Balance tracking: Real-time updates in dashboard
Usage stats: Detailed per-agent consumption

📈 ROI Tracking

Verification logs can include ROI values from an agent's stored ROI profile. If no ROI profile is stored, A2SPA uses a default fallback.

JSON - Custom ROI

{
  "roi": {
    "time_saved_minutes": 3,
    "value_usd": 0.08
  }
}

Default ROI fallback if not provided:

JSON - Default ROI

{ 
  "time_saved_minutes": 2, 
  "value_usd": 0.05 
}

📊

ROI Visibility: Track ROI across dashboard, CSV exports, and individual log entries. Example display: "📈 ROI: 2 min saved ($0.05)"

❓ Frequently Asked Questions

🔑 Account & Security

What happens if my balance hits 0?

Agent calls are blocked, a red alert is shown in the dashboard, but logs remain visible for review.

What if I lose my private key?

Private keys still cannot be retrieved, but you can now rotate an agent's keypair from the dashboard to issue a replacement.

Can I reset my API key?

Yes. Rotate it from the dashboard. The previous API key is revoked immediately, so update your scripts and agents right away. Stored API keys are hashed, so after migration you only see the full key at issue time.

🤖 Agent Management

Can I run multiple agents?

Yes! Each agent has its own keypair, logs, toggle status, and independent tracking.

How do I disable an agent instantly?

Use the toggle switch in your dashboard to turn agents ON/OFF immediately.

Can I customize ROI values?

The current dashboard does not expose ROI editing yet. If no stored ROI profile exists, logs use the default fallback values.

🔗 Agent Communication

Can agents respond to each other?

Yes. Agents can communicate bidirectionally as long as the sender has send permission and the target has receive permission. Delivery threading is added to the dashboard automatically.

How do agents chain together?

Each agent gets unique keypairs. Agent A signs the payload → sends it to A2SPA → A2SPA verifies and authorizes it before Agent B acts. Full cryptographic chain of custody.

🚀 Future Features (Roadmap)

Real-time payload explorer with graph visualization
Advanced developer usage analytics and alerting
Agent scheduling and auto-responder workflows
Webhook and streaming delivery options in addition to polling
Enhanced dashboard with more performance and inbox controls
Expanded AI builder workflows for multi-agent orchestration

💡

Need Help?
Email: hello@aiblockchainventures.com
Website: https://aimodularity.com