Execution Modes & Environments

2. Architecture, Environments, & OpenAPI Contracts

Execution Topologies Overview

DID.is supports three operational topologies:

┌────────────────────────────────────────────────────────────────────────────────┐
│                           DID.is EXECUTION TOPOLOGIES                          │
├───────────────────────┬───────────────────────────────┬────────────────────────┤
│ Mode 1: Public API    │ Mode 2: Project API           │ Mode 3: Embedded CLI   │
│ (https://did.is/api)  │ (Private Authenticated Gate)  │ (didis CLI binary)     │
├───────────────────────┼───────────────────────────────┼────────────────────────┤
│ • Zero credentials    │ • Scoped Bearer Tokens        │ • Fully Offline        │
│ • Anonymous Rate Limit│ • Isolated Usage Ledger       │ • Directly links Rust  │
│ • Shared In-Memory    │ • Dedicated Quotas            │   resolver-core engine │
│   Moka Cache          │ • Continuous Monitor & Hooks  │ • No daemon required   │
└───────────────────────┴───────────────────────────────┴────────────────────────┘

---

Multi-Environment Configuration Matrix

When integrating with DID.is, your application can transition seamlessly between local development, self-hosted Docker environments, and the public production API:

Environment	Base URL	W3C Standard Base	Recommended Usage	Authentication
Public Production API	https://did.is/api	https://did.is/api/1.0/identifiers	Default cloud resolver, production relying parties.	Anonymous (token bucket) or Bearer Token (didis_*).
Local Daemon	http://127.0.0.1:8080	http://127.0.0.1:8080/1.0/identifiers	Local development (cargo run -p resolver-core).	None by default (optional ADMIN_TOKEN).
Docker Compose	http://localhost:8080 (host) http://resolver-core:8080 (docker network)	http://resolver-core:8080/1.0/identifiers	Containerized integration tests, private microservices.	None or environment-configured tokens.

---

Switching Environments in SDKs

Both official SDKs provide native configuration options to target local or self-hosted daemons via environment variables or explicit client constructor parameters.

TypeScript SDK Environment Switching

import { DidisClient } from "@didis/client";

// Read from process environment or default to local daemon for development
const baseUrl = process.env.DIDIS_BASE_URL ?? "http://127.0.0.1:8080";

export const didis = new DidisClient({
  baseUrl,
  timeoutMs: 15_000,
});

Python SDK Environment Switching

import os
from didis import DidisClient, AsyncDidisClient

base_url = os.getenv("DIDIS_BASE_URL", "http://127.0.0.1:8080")

# Synchronous
client = DidisClient(base_url=base_url, timeout=15.0)

# Asynchronous
async_client = AsyncDidisClient(base_url=base_url, timeout=15.0)

---

OpenAPI & Raw JSON Endpoints

DID.is exposes clean, deterministic HTTP JSON interfaces adhering to RFC 8785 (JCS) and RFC 9457:

1. Core Service Readiness & Health

• GET /health: Returns service metadata, version, uptime, supported DID methods (key, jwk, web, webvh), and standards registry.
• GET /ready: Health check endpoint returning HTTP 200 {"ready": true} for Kubernetes / Docker liveness probes.
• GET /v1/status: Comprehensive status probe reporting memory cache stats, egress semaphore counts, and DB connection states.

2. Standard W3C Endpoints

• GET /1.0/identifiers/{did}: W3C Candidate Recommendation Draft DID Resolution v1 endpoint supporting content negotiation via Accept: application/did-resolution.

3. Enriched Evidence & Workbench Endpoints

• GET /v1/resolve/{did}: Complete enriched dossier with orthogonal evidence dimensions, SVG graph nodes, and microsecond telemetry.
• GET /v1/stream/{did}: Real-time Server-Sent Events (SSE) stream of resolution execution stages.
• GET /v1/dereference/{didUrl}: Dereferences verification method fragments, service endpoints, and relative refs.
• GET /v1/graph/{did}: Directed Acyclic Graph (DAG) nodes and edges for visual evidence rendering.
• GET /v1/history/{did}: Historical observations recorded in SQLite.
• GET /v1/diff/{did}: Semantic diff between historical observations.
• POST /v1/credentials/verify: Audits W3C Data Integrity and VC-JWT credentials with fail-closed status lists.
• POST /v1/policies/evaluate: Evaluates declarative ingress rulesets against live DIDs.
• GET /v1/mcp/inspect: Inspects Model Context Protocol (MCP) tool servers for schema drift and security classifications.
• GET /v1/a2a/inspect: Audits Agent-to-Agent (A2A) protocol cards and JWS publisher signatures.
• POST /v1/agents/verify-delegation: Verifies multi-hop Delegation Receipt v1 chains.
• POST /v1/agents/authorize: Checks dynamic tool authorization against a delegation chain.
• GET /v1/agents/verify-tool: Evaluates authorization for an agent against registered delegation chains in core SQLite.
• GET /v1/fast-verify/did/{did}: High-throughput, lightweight verdict check returning essential keys and dimension statuses.
• POST /v1/fast-verify/jws: Validates detached or compact JWS signatures against published verification relationships.

---