# WIA-EDU-011 Digital Credential Standard v1.1

## Phase 2: API Interface & Integration

**Status:** ✅ Complete
**Version:** 1.1.0
**Date:** 2025-01-15
**Philosophy:** 弘익人間 (Benefit All Humanity)

---

## 1. Overview

Phase 2 extends Phase 1 by defining RESTful API specifications for credential issuance, verification, revocation, and wallet integration. This enables interoperability between credential issuers, holders, and verifiers.

## 2. Scope

Phase 2 covers:
- RESTful API endpoints
- Authentication and authorization
- Credential issuance protocol
- Verification protocol
- Revocation mechanisms
- Wallet integration
- Error handling and status codes

## 3. API Architecture

### 3.1 Base URL Structure

```
https://api.{institution}.edu/wia/v1/credentials
```

### 3.2 Authentication

**OAuth 2.0 + OpenID Connect:**
- Authorization Code Flow for user authentication
- Client Credentials Flow for service-to-service
- JWT access tokens with 1-hour expiration

## 4. Credential Issuance API

### 4.1 Issue Credential

**Endpoint:** `POST /credentials/issue`

**Request:**
```json
{
  "credentialType": "BachelorDegree",
  "recipientDID": "did:wia:student:alice",
  "recipientEmail": "alice@example.com",
  "achievement": {
    "degree": "Bachelor of Science",
    "field": "Computer Science",
    "gpa": "3.85",
    "graduationDate": "2024-06-15"
  },
  "deliveryMethod": ["wallet", "email"]
}
```

**Response (201 Created):**
```json
{
  "credentialId": "did:wia:edu:mit:degree:12345",
  "credential": { /* full VC JSON-LD */ },
  "blockchainTxHash": "0x...",
  "qrCode": "data:image/png;base64,...",
  "downloadUrl": "https://credentials.mit.edu/download/12345"
}
```

## 5. Credential Verification API

### 5.1 Verify Credential

**Endpoint:** `POST /credentials/verify`

**Request:**
```json
{
  "credential": { /* VC JSON-LD */ },
  "verificationOptions": {
    "checkRevocation": true,
    "checkExpiration": true,
    "trustRegistry": ["wia-global", "us-chea"]
  }
}
```

**Response (200 OK):**
```json
{
  "verified": true,
  "checks": [
    {"type": "signature", "status": "passed"},
    {"type": "revocation", "status": "passed"},
    {"type": "expiration", "status": "passed"},
    {"type": "trustRegistry", "status": "passed"}
  ],
  "issuer": {
    "did": "did:wia:edu:mit",
    "name": "MIT",
    "verified": true
  },
  "credentialSubject": {
    "achievement": "Bachelor of Science in Computer Science"
  }
}
```

## 6. Credential Revocation API

### 6.1 Revoke Credential

**Endpoint:** `POST /credentials/revoke`

**Request:**
```json
{
  "credentialId": "did:wia:edu:mit:degree:12345",
  "reason": "Credential issued in error",
  "revocationDate": "2024-12-01T00:00:00Z"
}
```

**Response (200 OK):**
```json
{
  "credentialId": "did:wia:edu:mit:degree:12345",
  "revoked": true,
  "revocationDate": "2024-12-01T00:00:00Z",
  "blockchainTxHash": "0x..."
}
```

### 6.2 Check Revocation Status

**Endpoint:** `GET /credentials/{id}/status`

**Response:**
```json
{
  "credentialId": "did:wia:edu:mit:degree:12345",
  "status": "active",
  "issuanceDate": "2024-06-15T00:00:00Z",
  "lastChecked": "2025-01-15T10:30:00Z"
}
```

## 7. Wallet Integration APIs

### 7.1 Credential Presentation Request

**Endpoint:** `POST /presentations/request`

**Request:**
```json
{
  "verifier": "did:wia:employer:acme",
  "credentialTypes": ["BachelorDegree", "MasterDegree"],
  "selectiveDisclosure": {
    "required": ["degree", "field", "graduationDate"],
    "optional": ["gpa", "honors"]
  }
}
```

### 7.2 Submit Presentation

**Endpoint:** `POST /presentations/submit`

**Request:**
```json
{
  "presentation": { /* VP JSON-LD */ },
  "challenge": "abc123...",
  "domain": "employer.acme.com"
}
```

## 8. Batch Operations

### 8.1 Batch Issuance

**Endpoint:** `POST /credentials/batch/issue`

**Request:**
```json
{
  "credentials": [
    { /* credential 1 data */ },
    { /* credential 2 data */ },
    { /* ... */ }
  ],
  "blockchainBatch": true
}
```

## 9. Error Handling

### 9.1 Error Response Format

```json
{
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Cryptographic signature verification failed",
    "details": {
      "verificationMethod": "did:wia:edu:mit#key-1",
      "algorithm": "Ed25519Signature2020"
    }
  }
}
```

### 9.2 HTTP Status Codes

- `200 OK` - Successful operation
- `201 Created` - Credential issued
- `400 Bad Request` - Invalid request data
- `401 Unauthorized` - Authentication required
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Credential not found
- `409 Conflict` - Credential already exists
- `422 Unprocessable Entity` - Validation failed
- `500 Internal Server Error` - Server error

## 10. Rate Limiting

**Default Limits:**
- Issuance: 100 requests/hour
- Verification: 1000 requests/hour
- Revocation: 50 requests/hour

**Headers:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

## 11. Webhooks

### 11.1 Credential Status Changes

**Event:** `credential.revoked`

**Payload:**
```json
{
  "event": "credential.revoked",
  "credentialId": "did:wia:edu:mit:degree:12345",
  "timestamp": "2024-12-01T00:00:00Z",
  "reason": "Credential issued in error"
}
```

## 12. API Security

### 12.1 HTTPS Only

- All API endpoints MUST use HTTPS/TLS 1.3
- HTTP connections MUST redirect to HTTPS

### 12.2 API Key Management

- Rotate API keys every 90 days
- Store keys in secure key management systems
- Never log API keys

## 13. Compliance

Phase 2 APIs MUST comply with:
- ✅ OpenAPI 3.1 specification
- ✅ OAuth 2.0 / OpenID Connect
- ✅ RESTful API best practices
- ✅ GDPR data protection requirements
- ✅ W3C VC HTTP API specification

---

**Philosophy:** 弘益人間 (Benefit All Humanity)

*WIA-EDU-011 Digital Credential Standard*

© 2025 MIT License