Skip to content

Core Concepts

Understanding CertusOrdo's architecture and terminology.

The Problem We Solve

AI agents are autonomous systems that can:

  • Access APIs and databases
  • Execute transactions
  • Modify files and data
  • Interact with external systems

But what happens when they make mistakes?

Traditional authentication answers "Can this agent do this?" CertusOrdo answers "What happens when an authenticated agent does something wrong?"

Five-Layer Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    CERTUSRODO PLATFORM                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │   IDENTITY   │  │     AUTH     │  │   TRANSACTION LAYER  │  │
│  │    LAYER     │  │    LAYER     │  │  (Safety + Rollback) │  │
│  │  (Ed25519)   │  │    (JWT)     │  │                      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│         │                │                      │               │
│         └────────────────┼──────────────────────┘               │
│                          │                                      │
│                   ┌──────▼──────┐                               │
│                   │  AUDIT LOG  │                               │
│                   │ (Immutable) │                               │
│                   └─────────────┘                               │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                       API GATEWAY                               │
├─────────────────────────────────────────────────────────────────┤
│            SDKs: Python │ TypeScript │ Go │ REST               │
└─────────────────────────────────────────────────────────────────┘

Key Concepts

Organizations

An organization is a tenant in CertusOrdo. Each organization has:

  • A unique ID
  • An API key (for server-side operations)
  • Multiple agents
# Organizations own agents
org = client.organizations.get("org-id")
agents = client.agents.list()  # Returns agents for your org

Agents

An agent is an AI system with a cryptographic identity:

  • Ed25519 keypair - Cryptographic identity
  • Secret - Used to obtain JWT tokens
  • Scopes - Permissions (e.g., ["read", "write"])
  • Status - active, suspended, or revoked
agent = client.agents.create(
    name="data-processor",
    scopes=["data:read", "data:write"]
)

Authentication Flow

┌─────────┐         ┌───────────┐         ┌─────────────┐
│  Agent  │         │ CertusOrdo│         │ Your System │
└────┬────┘         └─────┬─────┘         └──────┬──────┘
     │                    │                      │
     │ 1. agent_id+secret │                      │
     │───────────────────>│                      │
     │                    │                      │
     │ 2. JWT tokens      │                      │
     │<───────────────────│                      │
     │                    │                      │
     │ 3. Request + JWT   │                      │
     │────────────────────┼─────────────────────>│
     │                    │                      │

Sessions

A session is a bounded operational context with limits:

  • max_actions - Maximum operations allowed
  • max_value_usd - Maximum total value
  • expires_at - Time limit

Sessions provide guardrails for agent operations:

session = client.sessions.create(
    agent_id=agent.id,
    max_actions=100,
    max_value_usd=10000.00,
    expires_in_seconds=3600
)

Transactions (The Moat)

A transaction captures state before and after an agent action:

Phase What Happens
BEGIN Capture pre_state - snapshot before action
EXECUTE Agent performs the action
COMMIT Capture post_state - snapshot after action
ROLLBACK Restore pre_state if something went wrong 
# The transaction lifecycle
txn = client.transactions.begin(pre_state={"balance": 1000})
# ... agent acts ...
client.transactions.commit(txn.id, post_state={"balance": 500})
# OR
client.transactions.rollback(txn.id)  # Restore original state

Audit Log

Every action is recorded in an immutable, hash-chained audit log:

  • Each entry contains a hash of the previous entry
  • Tampering is cryptographically detectable
  • Required for compliance (SOC 2, HIPAA, SEC)
# Verify chain integrity
verification = client.audit.verify()
print(f"Chain valid: {verification.is_valid}")

Security Model

Component Algorithm Purpose
Agent Identity Ed25519 Cryptographic keypairs
JWT Signing HS256 Token authentication
API Key Storage SHA256 Never stored plaintext
Audit Chain SHA256 Tamper-evident logging

Why This Matters

For Regulated Industries

Industry Requirement CertusOrdo Solution
Finance Reverse erroneous transactions Transaction rollback
Healthcare HIPAA audit trails Immutable audit log
Legal Chain of custody Hash-chained entries

For AI Safety

  • Guardrails: Sessions limit what agents can do
  • Accountability: Every action is logged
  • Reversibility: Mistakes can be undone

Next Steps