Developer documentation · v0.2.0

Build with verifiable outcomes.

This hosted website is a static preview. API endpoints below describe private local development software and are not live on this domain.

The working reference API protects a local invoice sandbox, collects readback evidence, and emits signed claim decisions. These docs describe what is implemented—not an unbuilt enterprise service.

Documentation index

Local quick start · Identity & auth · Invoice execution · Claims & receipts · Limits

1. Local quick start

Install Python 3.11+ dependencies, start the local demo runner, then open the private workspace or laboratory. The runner generates local-only development secrets, starts the mock provider, and starts the website.

python -m pip install -e '.[test]'
python run_website.py
# Open http://127.0.0.1:8765

The launcher prints initial local admin credentials only on first initialization. Never publish those credentials or the local provider.

2. Authentication

Human operators use Argon2 password credentials and server-side cookie sessions with CSRF protection. Machine agents use individually issued, revocable bearer tokens in the reference API. These are development controls, not production workload federation.

Authorization: Bearer <private-agent-token>
Idempotency-Key: <unique-key-12+-characters>

3. Execute a sandbox invoice

Scope: invoice.create. A deterministic delegated limit is enforced before the provider receives a request.

POST /v1/sandbox/invoices
Content-Type: application/json
{
  "tenant": "demo",
  "customer": "Example Customer",
  "amount_minor": 2350,
  "currency": "USD",
  "reference": "SAMPLE-001"
}

4. Review evidence

GET  /v1/claims/{claim_id}
GET  /v1/claims/{claim_id}/evidence
GET  /v1/claims/{claim_id}/receipts
POST /v1/claims/{claim_id}/recheck
GET  /v1/verification-public-key

Decisions include VERIFIED_WITHIN_SCOPE, CONFLICTING_EVIDENCE, INSUFFICIENT_EVIDENCE, PENDING and UNABLE_TO_VERIFY_SOURCE. Old signed receipts are preserved when a later recheck changes the result.

5. Explicit limitations

A matching invoice record in the mock destination is not evidence of payment. Separate write/read credentials do not establish organizational independence. A signed receipt authenticates an assertion under a key model; it does not prove that the underlying statement is true.

Do not deploy the reference implementation with production payment credentials or customer data. Security review, workload identity, durable workflow recovery, managed key custody, PostgreSQL isolation, monitoring and operating controls remain release gates.

Architecture overview

Separate the action from the proof.

Client / agent

Authenticated, tenant-scoped identity submits exact action.

Policy gateway

Check permitted operations, amount cap and idempotency.

Sandbox executor

Write to separate mock invoice provider.

Read-only verifier

Retrieve destination record via different scoped credential.

Claim engine

Assess provenance, source dependence, field correspondence and contradictions.

Signed receipt

Return a scoped conclusion with a transparent limitation statement.

Integrated API reference

Once the backend runs locally, the generated OpenAPI reference is accessible to development operators. Do not mistake accessible documentation for a production security review.

You are reading the product guide

The internal machine-readable OpenAPI endpoint remains available at /openapi.json.

Developer resources

Interactive engine →
Security & readiness →
Local operator workspace →