Chapter 5: Phase 2 - API Interface Design

Introduction to API Phase

Phase 2 of WIA-LEG-006 transforms the data formats from Phase 1 into actionable APIs that enable programmatic interaction with digital asset inheritance systems. These RESTful APIs allow wallets, estate planning platforms, executors, and beneficiaries to create, query, update, and execute inheritance plans in a standardized, interoperable manner.

This chapter provides comprehensive API specifications including endpoints, request/response formats, authentication mechanisms, error handling, and integration patterns. Developers can use these specifications to build compliant applications or integrate existing systems with WIA-LEG-006 infrastructure.

API Architecture

Base URL and Versioning

All WIA-LEG-006 APIs follow a consistent URL structure:

https://api.{provider}.com/wia/leg-006/v1/{resource}

Version is included in the URL path to enable smooth API evolution while maintaining backwards compatibility. Breaking changes require a new major version (v2, v3, etc.), while minor updates and bug fixes maintain the same version.

Authentication and Authorization

Phase 2 APIs implement OAuth 2.0 with JWT tokens for authentication, supplemented by additional verification for sensitive operations:

Operation Type	Authentication Required	Additional Verification
Read public plan info	API Key	None
Read full plan details	OAuth 2.0 + JWT	Owner/Beneficiary identity
Create/Update plan	OAuth 2.0 + JWT	MFA + Biometric
Execute inheritance	OAuth 2.0 + JWT	Multi-party signatures + Legal docs
Emergency access	Hardware security key	Court order verification

Core API Endpoints

Inheritance Plan Management

POST /plans

Description: Create a new inheritance plan

Request Body:

{
  "owner": {
    "did": "did:wia:owner:abc123",
    "authentication": {
      "method": "biometric",
      "token": "jwt-token-here"
    }
  },
  "plan": {
    // Complete Phase 1 data structure
  },
  "encryption": {
    "publicKey": "owner-public-key",
    "algorithm": "RSA-4096"
  }
}

Response:

{
  "planId": "plan-7f9fade1c0d5",
  "status": "created",
  "version": "1.0",
  "createdAt": "2025-01-15T10:30:00Z",
  "encryptionFingerprint": "sha256:abc...",
  "backupLocations": [
    "ipfs://QmX7KwXNFjKj8w3nQGxBvCvqV2zxK9yDhXjL8pTvWqRsN5",
    "arweave://tx-id-here"
  ]
}

GET /plans/{planId}

Description: Retrieve inheritance plan details

Query Parameters:

version (optional): Specific version to retrieve, defaults to latest
include (optional): Comma-separated list of sections (assets,beneficiaries,distribution)
decrypt (optional): Return decrypted sensitive fields (requires additional auth)

Response:

{
  "planId": "plan-7f9fade1c0d5",
  "version": "1.2",
  "status": "active",
  "lastModified": "2025-01-20T14:45:00Z",
  "plan": {
    // Phase 1 data structure
  },
  "permissions": {
    "canModify": true,
    "canExecute": false,
    "canView": ["metadata", "beneficiaries"]
  }
}

PUT /plans/{planId}

Description: Update existing inheritance plan

Request Body:

{
  "currentVersion": "1.1",
  "changes": {
    "assets": {
      "add": [/* new asset objects */],
      "update": [/* modified assets */],
      "remove": ["asset-id-1", "asset-id-2"]
    },
    "beneficiaries": {
      "update": [/* modified beneficiary allocations */]
    }
  },
  "changeReason": "Added new Bitcoin holdings and NFT collection",
  "authentication": {
    "mfa": "123456",
    "biometric": "fingerprint-hash"
  }
}

Response:

{
  "planId": "plan-7f9fade1c0d5",
  "newVersion": "1.2",
  "previousVersionHash": "sha256:7f9fa...",
  "changesApplied": 15,
  "warnings": [
    "Beneficiary allocation now totals 105% - review distribution rules"
  ]
}

DELETE /plans/{planId}

Description: Revoke inheritance plan (does not delete from blockchain)

Request Body:

{
  "revocationReason": "Creating new plan",
  "authentication": {
    "mfa": "123456",
    "confirmationPhrase": "I understand this action cannot be undone"
  }
}

Asset Discovery and Inventory

POST /assets/discover

Description: Scan for digital assets across blockchains and platforms

Request Body:

{
  "owner": "did:wia:owner:abc123",
  "searchCriteria": {
    "walletAddresses": [
      "bc1q...",
      "0x123..."
    ],
    "blockchains": ["Bitcoin", "Ethereum", "Polygon", "Solana"],
    "platforms": ["OpenSea", "Decentraland", "ENS"],
    "timeRange": {
      "from": "2020-01-01",
      "to": "2025-01-15"
    }
  },
  "includeHistory": true,
  "estimateValues": true
}

Response:

{
  "discoveryId": "disc-xyz789",
  "status": "completed",
  "assetsFound": 47,
  "totalEstimatedValue": {
    "amount": 892000,
    "currency": "USD"
  },
  "assets": [
    // Array of discovered assets in Phase 1 format
  ],
  "recommendations": [
    "Consider adding 12 NFTs currently not in inheritance plan",
    "Bitcoin holdings on 3 addresses detected - consolidate for easier management"
  ]
}

Beneficiary Management

POST /beneficiaries/verify

Description: Verify beneficiary identity and inheritance rights

Request Body:

{
  "planId": "plan-7f9fade1c0d5",
  "beneficiary": {
    "did": "did:wia:beneficiary:alice123",
    "credentials": {
      "governmentId": "encrypted-id-scan",
      "verifiableCredential": "VC-jwt-token",
      "biometric": "facial-recognition-data"
    }
  },
  "verificationLevel": "high-assurance"
}

Response:

{
  "verificationId": "ver-abc456",
  "status": "verified",
  "confidence": 0.99,
  "beneficiaryId": "ben-001",
  "entitlements": {
    "assets": ["asset-crypto-001", "asset-nft-001"],
    "percentage": 50,
    "estimatedValue": 445000,
    "conditions": {
      "ageRequirement": {
        "required": 25,
        "current": 24,
        "eligible": "2026-03-22"
      }
    }
  },
  "nextSteps": [
    "Wait until age 25 for full distribution",
    "Trust distributions will begin on schedule"
  ]
}

Trigger Management

POST /triggers/checkin

Description: Owner check-in to reset dead man's switch

Request Body:

{
  "planId": "plan-7f9fade1c0d5",
  "authentication": {
    "method": "biometric",
    "data": "fingerprint-template",
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    "deviceId": "iPhone-ABC123"
  }
}

Response:

{
  "checkInId": "checkin-timestamp-12345",
  "status": "confirmed",
  "nextCheckInDue": "2026-01-15T10:30:00Z",
  "daysUntilTrigger": 365,
  "notificationSettings": {
    "firstWarning": 335,
    "secondWarning": 350,
    "finalWarning": 358
  }
}

POST /triggers/execute

Description: Trigger inheritance execution (authorized parties only)

Request Body:

{
  "planId": "plan-7f9fade1c0d5",
  "trigger": {
    "type": "manual-executor",
    "reason": "Owner deceased",
    "documentation": [
      {
        "type": "death-certificate",
        "issuer": "California Department of Public Health",
        "documentHash": "sha256:abc...",
        "storageUrl": "ipfs://QmX..."
      },
      {
        "type": "letters-testamentary",
        "issuer": "San Francisco Superior Court",
        "caseNumber": "PES-2025-12345"
      }
    ]
  },
  "executors": [
    {
      "did": "did:wia:executor:xyz789",
      "signature": "digital-signature-1"
    },
    {
      "did": "did:wia:attorney:legal456",
      "signature": "digital-signature-2"
    }
  ]
}

Response:

{
  "executionId": "exec-timestamp-67890",
  "status": "initiated",
  "validationResults": {
    "documentationComplete": true,
    "signaturesValid": true,
    "legalRequirementsMet": true
  },
  "timeline": {
    "notificationPeriod": "7 days",
    "contestPeriod": "30 days",
    "estimatedDistribution": "2025-03-15"
  },
  "nextSteps": [
    "Beneficiaries will be notified within 24 hours",
    "Assets will be locked pending contest period",
    "Distribution will occur automatically unless contested"
  ]
}

Webhook System

The API supports webhooks for real-time notifications of important events:

Event Type	Description	Payload Example
plan.created	New plan created	{"planId": "...", "owner": "...", "timestamp": "..."}
plan.updated	Plan modified	{"planId": "...", "version": "...", "changes": [...]}
trigger.warning	Inactivity warning	{"planId": "...", "daysRemaining": 30, "severity": "high"}
trigger.activated	Inheritance triggered	{"planId": "...", "triggerType": "...", "executionId": "..."}
distribution.initiated	Asset distribution started	{"executionId": "...", "beneficiaries": [...], "assets": [...]}
distribution.completed	Distribution finished	{"executionId": "...", "status": "success", "transactions": [...]}

Webhook Configuration

POST /webhooks

Description: Register webhook endpoint

Request Body:

{
  "url": "https://myapp.com/webhooks/wia-leg-006",
  "events": ["trigger.warning", "trigger.activated", "distribution.completed"],
  "authentication": {
    "method": "hmac-sha256",
    "secret": "webhook-secret-key"
  },
  "retryPolicy": {
    "maxAttempts": 5,
    "backoff": "exponential"
  }
}

Error Handling

All API errors follow a consistent format:

{
  "error": {
    "code": "INSUFFICIENT_AUTH",
    "message": "Multi-factor authentication required for this operation",
    "details": {
      "requiredFactors": ["password", "biometric"],
      "providedFactors": ["password"]
    },
    "timestamp": "2025-01-15T10:30:00Z",
    "requestId": "req-abc123",
    "documentation": "https://docs.wia.org/leg-006/errors/INSUFFICIENT_AUTH"
  }
}

HTTP Status	Error Code	Description
400	INVALID_REQUEST	Malformed request body or parameters
401	UNAUTHORIZED	Missing or invalid authentication
403	INSUFFICIENT_AUTH	Additional verification required
404	NOT_FOUND	Plan or resource does not exist
409	CONFLICT	Version conflict or concurrent modification
422	VALIDATION_ERROR	Data validation failed
429	RATE_LIMIT	Too many requests
500	INTERNAL_ERROR	Server error

Chapter Summary: Key Takeaways

RESTful Design: Phase 2 APIs follow REST principles with clear resource-oriented URLs, standard HTTP methods, and predictable response formats.
Layered Security: Different operations require different authentication levels, from simple API keys to multi-factor biometric verification and multi-party signatures.
Comprehensive Endpoints: APIs cover the complete inheritance lifecycle from plan creation and asset discovery through trigger management and distribution execution.
Real-Time Notifications: Webhook system enables applications to respond immediately to critical events like trigger warnings and distribution initiation.
Developer-Friendly: Consistent error handling, comprehensive documentation, and predictable behaviors reduce integration complexity.
Interoperability Foundation: Standardized APIs enable diverse applications—wallets, estate planners, exchanges, custodians—to interoperate seamlessly.

Review Questions

Why does the API use URL-based versioning rather than header-based versioning, and what are the trade-offs?
Explain the multi-level authentication system. Why do different operations require different authentication strengths?
How does the asset discovery API help address the "hidden assets" problem identified in Chapter 2?
Describe the complete workflow for triggering inheritance execution via the API, including all required documentation and signatures.
What is the purpose of the webhook system, and how does it enable real-time inheritance monitoring?
How do the error codes and consistent error format improve the developer experience when integrating with WIA-LEG-006 APIs?

            Looking Ahead: Chapter 6 examines Phase 3: Smart Contract Protocol, diving into the on-chain execution mechanisms that enable automated, trustless inheritance on blockchain networks. We'll explore multi-signature implementations, dead man's switch contracts, oracle integration, and cross-chain coordination.
        

Korea Standardization Infrastructure Mapping

Korea operates a comprehensive standards governance system through inter-ministerial cooperation. National Standards Council (under Prime Minister's Office, per Framework Act on National Standards Article 5) coordinates KATS (Korean Agency for Technology and Standards), MFDS (Ministry of Food and Drug Safety), MOTIE (Ministry of Trade, Industry and Energy), MSIT (Ministry of Science and ICT), MOIS (Ministry of the Interior and Safety), MOE (Ministry of Environment), MOHW (Ministry of Health and Welfare), MND (Ministry of National Defense), MCST (Ministry of Culture, Sports and Tourism), MOFA (Ministry of Foreign Affairs), MOJ (Ministry of Justice), and FSC (Financial Services Commission). Accreditation and Testing: KOLAS (Korea Laboratory Accreditation Scheme) accredits 800+ testing laboratories. KAS (Korea Accreditation System) accredits 50+ certification bodies. KTC (Korea Testing Certification), KTR (Korea Testing & Research Institute), KTL (Korea Testing Laboratory), and KCL (Korea Conformity Laboratories) provide conformance testing. Telecom and Cyber: KCC (Korea Communications Commission), KCA (Korea Communications Agency), TTA (Telecommunications Technology Association), IITP (Institute for Information & Communications Technology Planning & Evaluation), NIPA (National IT Industry Promotion Agency), KISA (Korea Internet & Security Agency), KCMVP (Korea Cryptographic Module Validation Program), NIS (National Intelligence Service), NSR (National Security Research Institute), and NCSC (National Cyber Security Center). National R&D Centers: KIST, ETRI, KAIST, Seoul National University, Yonsei University, Korea University, POSTECH, UNIST, GIST, DGIST, KISTI, KIER, KIMM, KRICT, KFRI, KRIBB. International Standards Cooperation: ISO TC/SC Korean secretariats, IEC TC/SC Korean secretariats, ITU-T Study Group Korean chairs, 3GPP RAN/SA Korean chairs, IEEE 802 Korean chairs, W3C Korea office, OASIS Korea office, IETF Korea cooperation, OECD CSTP, UN ESCAP, APEC SCSC Korean cooperation. Korean Industrial Standards (KS) Catalog: KS X (Information) 25,000+, KS A (Basic) 15,000+, KS B (Machinery) 25,000+, KS C (Electrical) 18,000+, KS D (Metallurgy) 12,000+, KS E (Mining) 5,000+, KS F (Construction) 18,000+, KS H (Food) 8,000+, KS I (Environment) 5,000+, KS J (Biology) 3,000+, KS K (Textile) 15,000+, KS L (Ceramics) 7,000+, KS M (Chemistry) 12,000+, KS P (Medical) 5,000+, KS Q (Quality Mgmt) 4,000+, KS R (Transport) 12,000+, KS S (Service) 3,000+, KS T (Packaging) 4,000+, KS V (Shipbuilding) 5,000+, KS W (Aerospace) 3,000+ — totaling 220,000+ Korean Industrial Standards. Key Acts: Personal Information Protection Act (Act 19234, effective Sept 15, 2024), Electronic Government Act, Electronic Signature Act, Act on Promotion of Information and Communications Network Utilization and Information Protection, Information and Communications Infrastructure Protection Act, Data Industry Act, Public Data Act, AI Framework Act (Act 20212, effective July 2026), Industrial Technology Innovation Promotion Act, Framework Act on Science and Technology — 70+ Korean standardization-related laws.

Phase 2: API Interface Design

Introduction to API Phase

API Architecture

Base URL and Versioning

Authentication and Authorization

Core API Endpoints

Inheritance Plan Management

Asset Discovery and Inventory

Beneficiary Management

Trigger Management

Webhook System

Webhook Configuration

Error Handling

Chapter Summary: Key Takeaways

Review Questions

Korea Industrial, Research, Education Infrastructure Mapping

Korea Standardization Infrastructure Mapping

Korea Digital Transformation Detailed Mapping