Global Digital Identity logoGlobal Digital IdentityDecentralized Membership
OK
OpenAPI 3.1 · TLS 1.3 · Ed25519

API 文档

去中心化身份与会员管理系统的公开 REST API。所有端点强制 TLS 1.3；敏感操作需携带 `Authorization: Bearer <token>` 与 `X-Node-Signature` 节点签名。

下载 OpenAPI JSON在 Swagger Editor 中打开

鉴权

所有端点强制 TLS 1.3。敏感操作（注册、ZK 核验）必须同时携带以下两个 HTTP 头：

Authorization: Bearer

节点签发的 JWT/不透明令牌。生产环境由 WAIO_API_TOKEN 校验。

Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6...
X-Node-Signature

节点私钥对 (method + path + body) 的 Ed25519 签名，hex 编码。

X-Node-Signature: 7a3f9c1b...d20e8a

端点

POST/api/public/members/register Bearer + Node SigMembers

注册身份并签发 Global Digital Identity 与 VC

cURL 请求
bash
curl -X POST 'https://globaldigitalid.net/api/public/members/register' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Node-Signature: YOUR_NODE_SIGNATURE' \
  -d '{"subjectCode":"1001","regionCode":"CN-01","holderName":"Alice Chen","mnemonicLength":12}'
请求体示例
json
{
  "subjectCode": "1001",
  "regionCode": "CN-01",
  "holderName": "Alice Chen",
  "mnemonicLength": 12
}
响应
201身份创建成功，返回 Global Digital Identity、DID、助记词与 W3C VC。
json
{
  "ok": true,
  "gdiId": "732815940192837104",
  "did": "did:gdi:732815940192837104",
  "subjectType": "natural_person",
  "regionCode": "CN-01",
  "regionLabel": "中国 · 上海",
  "txHash": "0x9f3c1ab4e7d2061b8af31729cd5b48e60a2c7d5f9183642aeb15c70efa92cd",
  "blockHeight": 18127345,
  "issuedAt": "2026-05-23T08:14:22.118Z",
  "mnemonic": [
    "abandon",
    "ability",
    "able",
    "about",
    "above",
    "absent",
    "absorb",
    "abstract",
    "absurd",
    "abuse",
    "access",
    "accident"
  ],
  "vc": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://globaldigitalid.net/contexts/v1"
    ],
    "type": [
      "VerifiableCredential",
      "GlobalDigitalIdentityCredential"
    ],
    "issuer": "did:gdi:node:CN-01",
    "validFrom": "2026-05-23T08:14:22.118Z",
    "credentialSubject": {
      "id": "did:gdi:732815940192837104",
      "gdiId": "732815940192837104",
      "subjectType": "natural_person",
      "regionCode": "CN-01",
      "regionLabel": "中国 · 上海",
      "holderName": "Alice Chen"
    },
    "proof": {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-rdfc-2022",
      "created": "2026-05-23T08:14:22.118Z",
      "verificationMethod": "did:gdi:node:CN-01#key-1",
      "proofPurpose": "assertionMethod",
      "proofValue": "0x9f3c1ab4e7d2061b8af31729cd5b48e60a2c7d5f9183642aeb15c70efa92cd"
    }
  }
}
401缺失或无效的 Bearer / 节点签名
422请求体校验失败
500签发或存证失败
GET/api/public/members/recentMembers

获取最近注册的公开成员列表

Query 参数
名称类型默认说明
limitinteger20—
cURL 请求
bash
curl -X GET 'https://globaldigitalid.net/api/public/members/recent?limit=20' \
  -H 'Content-Type: application/json'
响应
200返回按时间倒序的成员列表
json
{
  "ok": true,
  "count": 2,
  "members": [
    {
      "id": "732815940192837104",
      "subject_code": "1001",
      "subject_type": "natural_person",
      "region_code": "CN-01",
      "region_label": "中国 · 上海",
      "holder_name": "Alice Chen",
      "status": "active",
      "created_at": "2026-05-23T08:14:22.118Z"
    },
    {
      "id": "732815940071904512",
      "subject_code": "1002",
      "subject_type": "legal_entity",
      "region_code": "SEA-02",
      "region_label": "新加坡",
      "holder_name": "Orion Labs Pte Ltd",
      "status": "active",
      "created_at": "2026-05-23T07:58:11.402Z"
    }
  ]
}
GET/api/public/attestationsAttestations

列出链上存证事件流

Query 参数
名称类型默认说明
limitinteger20—
event_typestring · register|verify|revoke|update——
member_idstring——
cURL 请求
bash
curl -X GET 'https://globaldigitalid.net/api/public/attestations?limit=20' \
  -H 'Content-Type: application/json'
响应
200返回存证事件
json
{
  "ok": true,
  "count": 1,
  "items": [
    {
      "id": 481923,
      "member_id": "732815940192837104",
      "event_type": "register",
      "node_code": "CN-01",
      "tx_hash": "0x9f3c1ab4e7d2061b8af31729cd5b48e60a2c7d5f9183642aeb15c70efa92cd",
      "block_height": 18127345,
      "payload": {
        "subject": "1001",
        "holder": "Alice Chen",
        "source": "api"
      },
      "created_at": "2026-05-23T08:14:22.118Z"
    }
  ]
}
GET/api/public/stats/globalStats

实时节点状态、成员分布与流量指标

cURL 请求
bash
curl -X GET 'https://globaldigitalid.net/api/public/stats/global' \
  -H 'Content-Type: application/json'
响应
200全局统计快照
json
{
  "ok": true,
  "generatedAt": "2026-05-23T08:20:00.000Z",
  "totals": {
    "members": 1284910,
    "attestations": 9382014,
    "attestations24h": 41203,
    "nodes": 7
  },
  "byRegion": [
    {
      "code": "CN-01",
      "label": "中国 · 上海",
      "count": 412305
    },
    {
      "code": "EU-03",
      "label": "法兰克福",
      "count": 287012
    }
  ],
  "byEventType": {
    "register": 1284910,
    "verify": 7918204,
    "revoke": 1820
  },
  "nodes": [
    {
      "code": "CN-01",
      "label": "中国 · 上海",
      "status": "active",
      "consensusLatencyMs": 942,
      "tps": 318,
      "uptimePct": 99.87
    }
  ]
}
POST/api/public/zk/verify Bearer + Node SigZK

零知识属性核验

cURL 请求
bash
curl -X POST 'https://globaldigitalid.net/api/public/zk/verify' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Node-Signature: YOUR_NODE_SIGNATURE' \
  -d '{"gdiId":"732815940192837104","claims":[{"attribute":"age_over","value":18},{"attribute":"region_in","value":["CN-01","SEA-02"]}],"proof":{"scheme":"groth16","publicSignals":["0x01","0x9f"],"proof":"0x2af3...c19d (groth16 proof bytes, base16-encoded, length 192-256 bytes)"},"nonce":"8f3a91c0b27e"}'
请求体示例
json
{
  "gdiId": "732815940192837104",
  "claims": [
    {
      "attribute": "age_over",
      "value": 18
    },
    {
      "attribute": "region_in",
      "value": [
        "CN-01",
        "SEA-02"
      ]
    }
  ],
  "proof": {
    "scheme": "groth16",
    "publicSignals": [
      "0x01",
      "0x9f"
    ],
    "proof": "0x2af3...c19d (groth16 proof bytes, base16-encoded, length 192-256 bytes)"
  },
  "nonce": "8f3a91c0b27e"
}
响应
200核验结果（成功或失败）
json
{
  "ok": true,
  "verified": true,
  "gdiId": "732815940192837104",
  "scheme": "groth16",
  "results": [
    {
      "attribute": "age_over",
      "value": 18,
      "satisfied": true
    },
    {
      "attribute": "region_in",
      "value": [
        "CN-01",
        "SEA-02"
      ],
      "satisfied": true
    }
  ],
  "verificationId": "0x71fa92cd0e8b4c1d5a3f29ab6e7194c8d20b3f5a1e4c9d72ab8f061c3e92zk",
  "verifiedAt": "2026-05-23T08:21:48.221Z",
  "nonce": "8f3a91c0b27e"
}
401缺失或无效的鉴权头
404subject_not_found
409subject_inactive
422请求体校验失败