Polygon ID Issuer Node API 全面解析

概述

Polygon ID Issuer Node 是一个用于创建和管理去中心化身份(DID)及可验证凭证(VC)的核心组件。本文将深入解析其API设计，帮助开发者理解如何利用这套API构建基于区块链的身份验证系统。

API核心功能

Polygon ID Issuer Node API 提供以下核心功能：

1. 身份管理：创建和管理DID身份
2. 凭证操作：颁发、查询和撤销可验证凭证(VC)
3. 认证流程：处理用户认证和连接建立
4. 状态管理：管理身份在区块链上的状态
5. 密钥管理：处理身份相关的密钥操作

主要API端点详解

1. 系统状态检查

GET /status

用于检查服务健康状态，返回200表示所有服务正常运行。

2. 身份管理接口

创建身份

POST /v2/identities

支持创建两种类型的密钥：

• BJJ密钥(Baby Jubjub)
• ETH密钥(区块链网络)

可选参数credentialStatusType定义核心声明的撤销验证方式。

获取身份列表

GET /v2/identities

返回所有已创建的身份数据。

获取身份详情

GET /v2/identities/{identifier}

获取特定身份的详细信息。

更新身份

PATCH /v2/identities/{identifier}

主要用于更新身份的显示名称(displayName)。

3. 身份状态管理

发布身份状态

POST /v2/identities/{identifier}/state/publish

将身份状态发布到区块链。

获取状态事务

GET /v2/identities/{identifier}/state/transactions

查询身份状态相关的事务记录，支持分页和筛选。

获取状态状态

GET /v2/identities/{identifier}/state/status

检查身份状态是否已发布，以及是否有待处理的操作。

4. 认证与连接

获取认证消息

POST /v2/{identifier}/authentication

生成认证消息，可用于创建QR码。支持两种返回类型：

• link：返回重定向链接(默认)
• raw：返回原始QR码内容

认证回调

POST /v2/authentication/callback

当用户扫描QR码并完成认证后，系统调用此端点建立连接。

管理连接

GET/DELETE /v2/identities/{identifier}/connections/{id}

获取或删除特定连接，删除时可选择是否同时撤销或删除相关凭证。

5. 凭证管理

创建认证凭证

POST /v2/identities/{identifier}/create-auth-credential

创建新的认证凭证，目前仅支持Baby Jubjub密钥。

安全机制

所有敏感操作都需要基本认证(basicAuth)，确保只有授权用户能访问关键功能。

最佳实践建议

1. 身份创建：根据应用场景选择合适的密钥类型(BJJ或ETH)
2. 状态管理：定期检查身份状态，确保区块链上的状态是最新的
3. 凭证撤销：在删除连接时考虑是否需要同时撤销相关凭证
4. 认证流程：根据客户端能力选择QR码返回类型(link或raw)

总结

Polygon ID Issuer Node API 提供了一套完整的去中心化身份管理解决方案，涵盖了从身份创建到凭证管理的全生命周期。通过合理利用这些API，开发者可以构建安全、可靠的区块链身份验证系统。