API Reference · v0.2.0

Documentation

Everything you need to integrate the AIP-1 protocol. Create agent passports, verify intents, and manage trust — all via REST.

Quick Start

Get from zero to verified agent in 3 API calls. All you need is an account and an API key.

Create an account & API key

Create an agent passport

Define what your agent can do — its identity, allowed actions, and spending limits.

Verify intents before execution

Every time your agent wants to act, call /api/verify first. Allowed → execute. Denied → block.

python

import requests

API_KEY = "kya_your_key_here"  # From Dashboard → API Keys
BASE    = "https://aip.synthexai.tech/api"

# Step 1: Create an agent passport (use JWT auth for management)
headers = {"Authorization": "Bearer YOUR_JWT_TOKEN"}
passport = requests.post(f"{BASE}/passports", json={
    "domain": "yourco.com",
    "agent_name": "procurement-bot",
    "allowed_actions": ["read_data", "send_email", "transfer_funds"],
    "monetary_limit_per_txn": 100.00,
    "monetary_limit_per_day": 1000.00
}, headers=headers).json()

print(passport["agent_id"])
# → "did:web:yourco.com:agents:procurement-bot"

# Step 2: Verify an intent before acting (use API Key auth)
result = requests.post(f"{BASE}/verify", json={
    "agent_id": passport["agent_id"],
    "action": "transfer_funds",
    "target": "did:web:vendor.com",
    "parameters": {"amount": 45.00, "currency": "USD"}
}, headers={"X-API-Key": API_KEY}).json()

if result["verified"]:
    print("✓ Intent allowed — execute action")
else:
    print(f"✗ Denied — {result['errors']}")

Authentication

The API uses two authentication methods. Use JWT tokens for dashboard/management endpoints, and API keys for programmatic access (verification, revocation).

JWT Token

For dashboard & management endpoints (passports, analytics, keys).

Authorization: Bearer eyJhbG...

API Key

For programmatic access — verification, revocation. Create in Dashboard → API Keys.

X-API-Key: kya_abc123...

Get a JWT token

curl

curl -X POST https://aip.synthexai.tech/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

# Response:
# {"access_token": "eyJhbG...", "token_type": "bearer"}

Create an API key

curl

curl -X POST https://aip.synthexai.tech/api/keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-backend"}'

# Response:
# {"id": "key_abc123", "key": "kya_live_...", "plan": "starter",
#  "message": "Save this key — it won't be shown again!"}

Agent Passports

A passport is a cryptographic identity for an AI agent. It defines who the agent is, what it's allowed to do, and its spending limits. Every passport gets an Ed25519 keypair and a DID (Decentralized Identifier).

POST/api/passportsJWT

Create a new agent passport with identity, action boundaries, and monetary limits.

Request Body

domainstring*

Your organization's domain (e.g. "yourco.com")

agent_namestring

Name of the agent (e.g. "procurement-bot")

allowed_actionsstring[]

Actions this agent is permitted to perform

denied_actionsstring[]

Explicitly blocked actions (takes priority over allowed)

monetary_limit_per_txnnumber

Max amount per single transaction ($)

monetary_limit_per_daynumber

Max total spend per day ($)

framework_idstring

Optional: "langchain", "autogpt", "crewai"

curl

curl -X POST https://aip.synthexai.tech/api/passports \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourco.com",
    "agent_name": "data-reader",
    "allowed_actions": ["read_data", "query_db"],
    "monetary_limit_per_txn": 0,
    "monetary_limit_per_day": 0
  }'

# Response:
# {
#   "agent_id": "did:web:yourco.com:agents:data-reader",
#   "public_key": "MCowBQYDK2VwAyEA...",
#   "status": "created"
# }

GET/api/passportsJWT

List all agent passports in your account.

curl

curl https://aip.synthexai.tech/api/passports \
  -H "Authorization: Bearer YOUR_JWT"

# Response:
# {
#   "agents": [
#     {
#       "id": "did:web:yourco.com:agents:data-reader",
#       "domain": "yourco.com",
#       "name": "data-reader",
#       "status": "active",
#       "trust_score": 0.85,
#       "allowed_actions": ["read_data", "query_db"],
#       "monetary_limit_txn": 0,
#       "revoked": false
#     }
#   ],
#   "total": 1
# }

GET/api/passports/{agent_id}JWT

Get full details for a specific agent, including trust history.

curl

curl "https://aip.synthexai.tech/api/passports/did:web:yourco.com:agents:data-reader" \
  -H "Authorization: Bearer YOUR_JWT"

# Response includes trust history:
# {
#   "id": "did:web:yourco.com:agents:data-reader",
#   "trust_score": 0.85,
#   "history": {
#     "total_intents": 142,
#     "successful_intents": 138,
#     "violations": 3,
#     "revocations": 0
#   }
# }

Verification

The core of AIP-1. Before your agent performs any action, call /api/verify to run the 8-step verification pipeline. The protocol checks identity, boundaries, revocation status, and computes a trust score — all in milliseconds.

Verification Pipeline (8 steps)

Agent Lookup— Find agent in registry

Revocation Check— Not revoked or suspended

Signature Verification— Ed25519 signature valid

Action Boundary— Action is in allow-list

Monetary Limit— Amount within limits

Geo Restriction— Region is permitted

Delegation Chain— Authority chain valid

Trust Score— Bayesian reputation check

POST/api/verifyAPI Key

Verify an agent's intent through the full 8-step pipeline. This is the primary endpoint for programmatic use.

Request Body

agent_idstring*

The agent's DID (e.g. "did:web:yourco.com:agents:my-bot")

actionstring*

Action the agent wants to perform (e.g. "transfer_funds")

targetstring

Target DID or identifier of the receiving party

parametersobject

Action-specific params. Include "amount" for monetary actions.

python

import requests

result = requests.post("https://aip.synthexai.tech/api/verify",
    headers={"X-API-Key": "kya_your_key"},
    json={
        "agent_id": "did:web:yourco.com:agents:procurement-bot",
        "action": "transfer_funds",
        "target": "did:web:vendor.com",
        "parameters": {"amount": 45.00}
    }
).json()

# ✓ Successful verification:
# {
#   "verified": true,
#   "tier": "tier_1",
#   "signature_valid": true,
#   "within_boundaries": true,
#   "attestation_match": true,
#   "revoked": false,
#   "trust_score": 0.847,
#   "latency_ms": 3.21,
#   "errors": [],
#   "detail": "All checks passed"
# }

# ✗ Failed verification:
# {
#   "verified": false,
#   "tier": "tier_1",
#   "within_boundaries": false,
#   "trust_score": 0.42,
#   "errors": [
#     {"code": "AIP-E200", "name": "ACTION_NOT_ALLOWED"}
#   ],
#   "detail": "Action 'delete_all' not in allowed_actions"
# }

Revocation & Kill Switch

Instantly revoke, suspend, or reinstate agents. Revocation takes effect immediately — all subsequent verification calls for that agent will be denied with zero propagation delay.

POST/api/revokeAPI Key

Permanently revoke an agent. All future intents will be denied immediately.

agent_idstring*

The DID of the agent to revoke

reasonstring

Human-readable reason for audit trail

curl

curl -X POST https://aip.synthexai.tech/api/revoke \
  -H "X-API-Key: kya_your_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "did:web:yourco.com:agents:rogue-bot", "reason": "compromised credentials"}'

# {"agent_id": "did:web:...", "status": "revoked", "reason": "compromised credentials"}

POST/api/suspendAPI Key

Temporarily suspend an agent for 1 hour. Auto-reinstates after expiry.

curl

curl -X POST https://aip.synthexai.tech/api/suspend \
  -H "X-API-Key: kya_your_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "did:web:yourco.com:agents:my-bot", "reason": "investigating anomaly"}'

# {"agent_id": "did:web:...", "status": "suspended",
#  "suspended_until": "2026-02-14T15:30:00+00:00"}

POST/api/reinstateAPI Key

Reinstate a previously revoked or suspended agent.

curl

curl -X POST https://aip.synthexai.tech/api/reinstate \
  -H "X-API-Key: kya_your_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "did:web:yourco.com:agents:my-bot"}'

# {"agent_id": "did:web:...", "reinstated": true, "status": "active"}

Trust Scores & Analytics

Every agent builds a trust score over time based on its verification history. The score uses a Bayesian model — successful verifications increase trust, violations and revocations decrease it.

GET/api/analyticsJWT

Get dashboard analytics — overview stats, hourly breakdown, and agent trust scores.

curl

curl https://aip.synthexai.tech/api/analytics \
  -H "Authorization: Bearer YOUR_JWT"

# {
#   "overview": {
#     "total_agents": 5,
#     "active_agents": 4,
#     "total_verifications": 1247,
#     "revoked_agents": 1
#   },
#   "trust_scores": [
#     {"agent_id": "did:web:yourco.com:agents:reader", "score": 0.92},
#     {"agent_id": "did:web:yourco.com:agents:writer", "score": 0.71}
#   ]
# }

GET/api/verifications?limit=50JWT

Get verification history (audit log). Max 200 per request.

curl

curl "https://aip.synthexai.tech/api/verifications?limit=10" \
  -H "Authorization: Bearer YOUR_JWT"

# {
#   "verifications": [
#     {
#       "id": "vrf_abc123",
#       "agent_id": "did:web:yourco.com:agents:bot",
#       "action": "read_data",
#       "passed": true,
#       "trust_score": 0.85,
#       "latency_ms": 2.4,
#       "timestamp": "2026-02-14T10:30:00Z"
#     }
#   ]
# }

API Key Management

POST/api/keysJWT

Create a new API key. The full key is returned only once — save it immediately.

namestring*

A label for this key (e.g. "production", "staging")

planstring

Plan tier: "starter" (default), "growth", or "enterprise"

GET/api/keysJWT

List all API keys for your account. Returns key prefix only (never the full key).

DELETE/api/keys/{key_id}JWT

Revoke an API key permanently. All requests using this key will return 401.

Error Codes

Every failure returns a machine-readable AIP-Exxx error code — not a generic 400. Your logs, dashboards, and audit trails show exactly what went wrong. Errors are returned in theerrors array with both a numeric code and a human-readable name.

json

// Every error in the response looks like this:
{
  "verified": false,
  "errors": [
    { "code": "AIP-E202", "name": "MONETARY_LIMIT" },
    { "code": "AIP-E303", "name": "INTENT_DRIFT" }
  ],
  "detail": "Transaction amount $5,200.00 exceeds per-txn limit of $1,000.00"
}

HTTP Status Codes

Status	Meaning
200	Request succeeded — check "verified" for verification outcome
400	Malformed request body or missing required fields
401	Invalid or missing API key / JWT token
403	Authenticated but not authorized for this resource
404	Agent, key, or resource not found
429	Rate limit exceeded — back off and retry
500	Internal server error — contact support

AIP Error Taxonomy

Five structured categories. Every code maps to a specific verification pipeline step.

E1xx — Envelope Errors

Signature & Schema

Code	Name	Description
AIP-E100	INVALID_SIGNATURE	Ed25519 cryptographic proof verification failed
AIP-E101	EXPIRED_ENVELOPE	Intent envelope TTL has been exceeded
AIP-E102	REPLAY_DETECTED	Entropy nonce reused — possible replay attack
AIP-E103	SCHEMA_INVALID	Envelope does not conform to AIP-1 schema
AIP-E104	VERSION_UNSUPPORTED	Protocol version not supported by this verifier

E2xx — Boundary Violations

Action, Monetary, Geo

Code	Name	Description
AIP-E200	ACTION_NOT_ALLOWED	Requested action is not in the agent's allowed_actions list
AIP-E201	ACTION_DENIED	Action is explicitly in the agent's denied_actions list
AIP-E202	MONETARY_LIMIT	Transaction amount exceeds per-txn or per-day monetary limit
AIP-E203	TIME_WINDOW_VIOLATION	Request is outside the agent's authorized time window
AIP-E204	GEO_RESTRICTION	Request originates from a restricted geography

E3xx — Attestation Failures

Model, Prompt, Framework, Drift

Code	Name	Description
AIP-E300	MODEL_HASH_MISMATCH	Model attestation hash does not match the registry
AIP-E301	PROMPT_HASH_MISMATCH	System prompt template hash has changed
AIP-E302	FRAMEWORK_UNREGISTERED	Agent framework is not registered in the attestation registry
AIP-E303	INTENT_DRIFT	Intent classifier flagged action as outside declared boundaries

E4xx — Trust Failures

Revocation, Delegation, Trust Score

Code	Name	Description
AIP-E400	AGENT_REVOKED	Agent identity has been globally revoked (Kill Switch)
AIP-E401	AGENT_SUSPENDED	Agent identity is temporarily suspended
AIP-E402	PRINCIPAL_REVOKED	Principal organization has been revoked
AIP-E403	DELEGATION_INVALID	Delegation chain is broken, expired, or violates monotonicity
AIP-E404	TRUST_SCORE_LOW	Agent trust score is below verifier's minimum threshold

E5xx — Protocol Errors

Mesh, Revocation Data, Timeout

Code	Name	Description
AIP-E500	MESH_UNAVAILABLE	Cannot reach the AIP verification mesh
AIP-E501	REVOCATION_STALE	Revocation data is older than max_staleness threshold
AIP-E502	HANDSHAKE_TIMEOUT	AIP verification handshake timed out

Handling Errors in Code

python

result = requests.post(f"{BASE}/verify", json={...},
    headers={"X-API-Key": API_KEY}).json()

if not result["verified"]:
    for err in result["errors"]:
        match err["code"]:
            case "AIP-E202":
                alert_compliance_team(f"Monetary limit breach: {result['detail']}")
            case "AIP-E400":
                log_critical(f"REVOKED agent attempted action: {err['name']}")
            case "AIP-E303":
                flag_for_review(f"Intent drift detected — possible prompt injection")
            case _:
                log_warning(f"Verification failed: {err['code']} {err['name']}")

Rate Limits

Rate limits are applied per IP or per API key. Every response includes rate limit headers.

Tier	Limit	Window
IP (unauthenticated)	60 requests	1 minute
API Key	300 requests	1 minute
Login attempts	10 attempts	5 minutes

Response Headers

http

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Window: 60s

Python SDK

Install the SDK for offline cryptographic operations — create passports, sign envelopes, and verify intents locally.

bash

pip install aip-protocol

View on GitHub

KYA Labs · AIP-1 Protocol

Home Dashboard GitHub

Documentation

On this page

Quick Start

Authentication

JWT Token

API Key

Get a JWT token

Create an API key

Agent Passports

Request Body

Verification

Verification Pipeline (8 steps)

Request Body

Revocation & Kill Switch

Trust Scores & Analytics

API Key Management

Error Codes

HTTP Status Codes

AIP Error Taxonomy

E1xx — Envelope Errors

E2xx — Boundary Violations

E3xx — Attestation Failures

E4xx — Trust Failures

E5xx — Protocol Errors

Handling Errors in Code

Rate Limits

Response Headers

Python SDK