# WIA-LEG-006: Digital Asset Inheritance Standard
## Version 1.1 - Phase 2: API Interface Specification

**Status:** Final
**Published:** 2025-02-01
**Authors:** WIA Technical Committee on Digital Legacy
**License:** MIT License
**Requires:** v1.0 (Phase 1 - Data Format)

---

## 1. Introduction

### 1.1 Purpose
Phase 2 defines RESTful APIs enabling programmatic interaction with digital asset inheritance systems built on Phase 1 data formats.

### 1.2 Scope
- HTTP REST API endpoints
- Authentication and authorization
- Request/response formats
- Webhook event system
- Error handling
- Rate limiting

---

## 2. API Architecture

### 2.1 Base URL Structure
```
https://api.{provider}.com/wia/leg-006/v1/{resource}
```

### 2.2 Authentication
- **Method:** OAuth 2.0 with JWT tokens
- **Token Lifetime:** 1 hour (access), 30 days (refresh)
- **Scopes:**
  - `plan:read` - Read inheritance plans
  - `plan:write` - Create/update plans
  - `plan:execute` - Trigger inheritance execution
  - `asset:discover` - Asset discovery operations
  - `beneficiary:verify` - Beneficiary verification

### 2.3 Additional Security
- Multi-Factor Authentication for sensitive operations
- Biometric verification for plan modifications
- Hardware security keys for emergency access

---

## 3. Core Endpoints

### 3.1 Plan Management

#### POST /plans
Create new inheritance plan
- **Auth:** OAuth 2.0 + MFA
- **Request:** Phase 1 inheritance plan JSON
- **Response:** `planId`, `version`, `createdAt`, `backupLocations`

#### GET /plans/{planId}
Retrieve inheritance plan
- **Auth:** OAuth 2.0
- **Query Params:**
  - `version` (optional): Specific version
  - `include` (optional): Sections to include
  - `decrypt` (optional): Decrypt sensitive fields
- **Response:** Complete plan data

#### PUT /plans/{planId}
Update existing plan
- **Auth:** OAuth 2.0 + MFA + Biometric
- **Request:** Change set with current version
- **Response:** New version number, change summary

#### DELETE /plans/{planId}
Revoke inheritance plan
- **Auth:** OAuth 2.0 + MFA + Confirmation phrase
- **Request:** Revocation reason
- **Response:** Revocation confirmation

### 3.2 Asset Discovery

#### POST /assets/discover
Scan for digital assets
- **Auth:** OAuth 2.0
- **Request:**
  ```json
  {
    "owner": "did:wia:owner:...",
    "searchCriteria": {
      "walletAddresses": [],
      "blockchains": [],
      "platforms": [],
      "timeRange": {}
    },
    "includeHistory": boolean,
    "estimateValues": boolean
  }
  ```
- **Response:** Discovered assets array, total estimated value

### 3.3 Beneficiary Management

#### POST /beneficiaries/verify
Verify beneficiary identity and rights
- **Auth:** OAuth 2.0
- **Request:** Beneficiary DID, credentials, verification level
- **Response:** Verification status, entitlements, next steps

### 3.4 Trigger Management

#### POST /triggers/checkin
Owner check-in to reset dead man's switch
- **Auth:** OAuth 2.0 + Biometric
- **Request:** Plan ID, authentication data, location
- **Response:** Confirmation, next check-in due date

#### POST /triggers/execute
Trigger inheritance execution
- **Auth:** OAuth 2.0 + Multi-party signatures
- **Request:** Plan ID, trigger reason, documentation, executor signatures
- **Response:** Execution ID, validation results, timeline

---

## 4. Webhook System

### 4.1 Event Types
- `plan.created` - New plan created
- `plan.updated` - Plan modified
- `plan.revoked` - Plan revoked
- `trigger.warning` - Inactivity warning
- `trigger.activated` - Inheritance triggered
- `distribution.initiated` - Asset distribution started
- `distribution.completed` - Distribution finished
- `dispute.filed` - Inheritance dispute filed

### 4.2 Webhook Configuration

#### POST /webhooks
Register webhook endpoint
- **Request:**
  ```json
  {
    "url": "https://...",
    "events": ["trigger.warning", "distribution.completed"],
    "authentication": {
      "method": "hmac-sha256",
      "secret": "..."
    },
    "retryPolicy": {
      "maxAttempts": 5,
      "backoff": "exponential"
    }
  }
  ```

### 4.3 Webhook Payload
```json
{
  "event": "trigger.activated",
  "timestamp": "2025-01-15T10:30:00Z",
  "planId": "...",
  "data": {},
  "signature": "HMAC-SHA256 signature"
}
```

---

## 5. Error Handling

### 5.1 Error Response Format
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {},
    "timestamp": "ISO 8601",
    "requestId": "UUID",
    "documentation": "https://docs.wiastandards.com/..."
  }
}
```

### 5.2 Standard Error Codes
- `400 INVALID_REQUEST` - Malformed request
- `401 UNAUTHORIZED` - Missing/invalid authentication
- `403 INSUFFICIENT_AUTH` - Additional verification required
- `404 NOT_FOUND` - Resource doesn't exist
- `409 CONFLICT` - Version conflict
- `422 VALIDATION_ERROR` - Data validation failed
- `429 RATE_LIMIT` - Too many requests
- `500 INTERNAL_ERROR` - Server error

---

## 6. Rate Limiting

### 6.1 Rate Limits by Endpoint
- Plan creation: 10 per hour
- Plan updates: 100 per hour
- Check-ins: 1000 per hour
- Asset discovery: 10 per day
- Webhook registration: 100 per day

### 6.2 Rate Limit Headers
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

---

## 7. Versioning

### 7.1 API Version Strategy
- Version in URL path (`/v1/`, `/v2/`)
- Breaking changes require new major version
- Backward compatible changes increment minor version
- Old versions supported for minimum 24 months

### 7.2 Deprecation Policy
- 12 months advance notice for deprecations
- Deprecated endpoints return `Sunset` header
- Migration guides provided

---

## 8. Security Requirements

### 8.1 Transport Security
- TLS 1.3 or higher required
- Certificate pinning recommended
- HSTS headers mandatory

### 8.2 Request Signing
- All mutating operations require request signatures
- Signature algorithm: Ed25519 or ECDSA
- Signature includes timestamp, prevents replay attacks

### 8.3 Data Privacy
- GDPR compliance: Right to erasure after distribution
- Data minimization: Collect only necessary information
- Encryption at rest and in transit

---

## 9. Compliance Features

### 9.1 Audit Logging
- All API calls logged with timestamps
- Immutable audit trail
- Accessible via `/audit-log` endpoint

### 9.2 Legal Requirements
- Support for jurisdictional data localization
- Ability to generate compliance reports
- Integration with tax reporting systems

---

## 10. Client Libraries

### 10.1 Official SDKs
- JavaScript/TypeScript (Browser + Node.js)
- Python 3.8+
- Java 11+
- Swift (iOS)
- Kotlin (Android)

### 10.2 SDK Features
- Automatic authentication token refresh
- Retry logic with exponential backoff
- Type-safe request/response models
- Built-in validation

---

## 11. Testing

### 11.1 Sandbox Environment
- URL: `https://api-sandbox.wiastandards.com/wia/leg-006/v1/`
- Test credentials provided
- Synthetic blockchain environments
- No real asset transfers

### 11.2 API Testing Tools
- Postman collection available
- OpenAPI 3.0 specification provided
- Automated integration tests in GitHub

---

## 12. References

- OAuth 2.0: RFC 6749
- JSON Web Tokens: RFC 7519
- OpenAPI Specification: https://spec.openapis.org/oas/v3.0.0
- RESTful API Design: https://restfulapi.net/

---

**弘益人間 · Benefit All Humanity**

© 2025 World Certification Industry Association
Licensed under MIT License