Skip to content

API Reference

Jump to bottom
Mohamed Abdelaziz ‬‏ edited this page Jun 25, 2026 · 1 revision

API Reference

Back to Home | See also: Architecture Deep-Dive

Base URLs

Production:  https://api.axiomid.dev/v1
Preview:     https://preview.api.axiomid.dev/v1
DID Resolver: https://resolver.axiomid.dev/1.0

Authentication

All authenticated endpoints require a DID-Auth JWT in the Authorization header:

Authorization: Bearer <did-auth-jwt>
X-DID: did:axiom:eth:agent:<id>

JWT Payload structure:

{
  "iss": "did:axiom:eth:agent:a3f2c8b4...",
  "sub": "did:axiom:eth:agent:a3f2c8b4...",
  "aud": "https://api.axiomid.dev",
  "exp": 1751000000,
  "iat": 1750996400,
  "nonce": "rnd_abc123"
}

DID Endpoints

POST /did/create

Create a new DID and DID Document.

Auth: None required
Soul Gate: None (public)

Request:

{
  "entityType": "agent",
  "network": "eth",
  "publicKey": "z6MkhaXgBZDvotDkL5257fai...",
  "keyType": "Ed25519VerificationKey2020",
  "serviceEndpoint": "https://myagent.dev/axiom"
}

Response 201:

{
  "did": "did:axiom:eth:agent:a3f2c8b4...",
  "document": { ... },
  "txHash": "0xabc123...",
  "ipfsCid": "bafybeig..."
}

GET /did/resolve/{did}

Resolve a DID to its DID Document.

Auth: None required
Soul Gate: None (public)

Response 200:

{
  "didDocument": { ... },
  "didResolutionMetadata": {
    "contentType": "application/did+ld+json",
    "duration": 12
  },
  "didDocumentMetadata": {
    "created": "2026-01-15T10:30:00Z",
    "updated": "2026-06-01T08:00:00Z",
    "deactivated": false,
    "versionId": "3"
  }
}

Error responses:

Code Meaning
404 DID not found
410 DID deactivated
503 Resolver unavailable

PUT /did/update

Update DID Document (key rotation).

Auth: Required
Soul Gate: Apprentice (1) + Trust Score ≥ 100

Request:

{
  "did": "did:axiom:eth:agent:a3f2c8b4...",
  "newPublicKey": "z6MkNewKey...",
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-06-25T20:00:00Z",
    "verificationMethod": "did:axiom:eth:agent:a3f2c8b4...#key-1",
    "proofValue": "z58DAdFfa9SkqZMVPxAkpfoQyi..."
  }
}

Trust Score Endpoints

GET /trust/score/{did}

Get the current trust score for a DID.

Auth: None (public endpoint)
Response 200:

{
  "did": "did:axiom:eth:agent:a3f2c8b4...",
  "score": 742,
  "tier": 3,
  "tierLabel": "Archon",
  "breakdown": {
    "onChainActivity": 185,
    "attestations": 220,
    "delegationHistory": 110,
    "behavioralSignals": 167,
    "socialGraph": 60
  },
  "lastUpdated": "2026-06-25T18:00:00Z",
  "sybilMultiplier": 1.0
}

POST /trust/attest

Issue an attestation for another DID.

Auth: Required
Soul Gate: Apprentice (1) + Trust Score ≥ 100

Request:

{
  "subjectDID": "did:axiom:eth:human:7b9e2f4a...",
  "credentialType": "ProfessionalCredential",
  "claims": {
    "role": "Senior Engineer",
    "organization": "AxiomLabs"
  },
  "expiresAt": "2027-06-25T00:00:00Z"
}

Response 201:

{
  "credentialId": "vc_abc123...",
  "issuerDID": "did:axiom:eth:agent:a3f2c8b4...",
  "subjectDID": "did:axiom:eth:human:7b9e2f4a...",
  "scoreImpact": "+24",
  "vcDocument": { ... }
}

Soul Gate Endpoints

POST /gate/check

Check if a DID can perform an action.

Auth: Required
Soul Gate: None (meta-gate endpoint)

Request:

{
  "did": "did:axiom:eth:agent:a3f2c8b4...",
  "action": "delegate.create",
  "context": {
    "targetDID": "did:axiom:eth:agent:x9z1y2...",
    "scope": ["read:identity", "attest:basic"]
  }
}

Response 200:

{
  "decision": "ALLOW",
  "did": "did:axiom:eth:agent:a3f2c8b4...",
  "trustScore": 742,
  "soulTier": 3,
  "gateChecks": [
    { "check": "sbt_ownership", "passed": true },
    { "check": "tier_requirement", "passed": true },
    { "check": "trust_threshold", "passed": true },
    { "check": "scope_validation", "passed": true }
  ]
}

Delegation Endpoints

POST /delegation/create

Create a delegation credential.

Auth: Required
Soul Gate: Guardian (2) + Trust Score ≥ 500

Request:

{
  "subjectDID": "did:axiom:eth:agent:x9z1y2...",
  "scope": ["read:identity", "attest:basic"],
  "maxDepth": 2,
  "expiresAt": "2026-12-31T00:00:00Z"
}

Response 201:

{
  "delegationId": "del_xyz789...",
  "credential": { ... },
  "verificationUrl": "https://api.axiomid.dev/v1/delegation/verify/del_xyz789"
}

MCP Tool Definitions

AxiomID exposes its capabilities as MCP tools for AI agent integration:

Tool: axiom_resolve_did 

{
  "name": "axiom_resolve_did",
  "description": "Resolve a did:axiom DID to its DID Document and trust score",
  "inputSchema": {
    "type": "object",
    "properties": {
      "did": { "type": "string", "description": "The DID to resolve" }
    },
    "required": ["did"]
  }
}

Tool: axiom_check_gate 

{
  "name": "axiom_check_gate",
  "description": "Check if a DID is authorized to perform an action",
  "inputSchema": {
    "type": "object",
    "properties": {
      "did": { "type": "string" },
      "action": { "type": "string" },
      "scope": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["did", "action"]
  }
}

Tool: axiom_delegate 

{
  "name": "axiom_delegate",
  "description": "Create a scoped delegation credential from one agent to another",
  "inputSchema": {
    "type": "object",
    "properties": {
      "issuerDID": { "type": "string" },
      "subjectDID": { "type": "string" },
      "scope": { "type": "array", "items": { "type": "string" } },
      "expiresAt": { "type": "string", "format": "date-time" }
    },
    "required": ["issuerDID", "subjectDID", "scope"]
  }
}

Rate Limits

Tier Requests/min Requests/day
Unauthenticated 10 500
Genesis (0) 30 5,000
Apprentice (1) 100 20,000
Guardian (2) 500 100,000
Archon (3) 2,000 500,000
Sovereign (4) Unlimited Unlimited

Error Format

All errors follow a consistent schema:

{
  "error": {
    "code": "INSUFFICIENT_TRUST_SCORE",
    "message": "Trust score 420 is below required threshold 500",
    "required": 500,
    "current": 420,
    "docs": "https://github.com/Moeabdelaziz007/AxiomID/wiki/Trust-Score-Algorithm"
  }
}

← Back to Home

Clone this wiki locally