DID Registry API
La DID Registry API es la interfaz HTTP que ISBE expone para que las entidades gestionen su DID directamente, sin necesidad de interactuar con la blockchain a bajo nivel. Está implementada con Node.js / Express y publicada en cada uno de los tres entornos.
- Versión actual:
v2.0.0(basepath/api/v1) - Formato: OpenAPI 3.0.3
- Especificación: disponible como
openapi.yamlen el repositorioisbe-identity-did-api.
URLs por entorno
| Entorno | Base URL | Swagger UI |
|---|---|---|
| PRE | https://did-registry.pre.portal.redisbe.com | /api |
| PRO | https://did-registry.portal.redisbe.com | /api/v1 |
Modelo de transacciones
La API distingue dos tipos de operaciones:
1. Consultas (GET)
Lectura directa del registro. No requieren firma. Se invocan y la respuesta es el dato solicitado.
GET /api/v1/identifiers— Listar DIDs.GET /api/v1/identifiers/{identifier}— Resolver DID Document.
2. Operaciones de escritura (POST /contract/...)
Cualquier endpoint bajo /contract/ NO ejecuta la transacción. Devuelve una transacción sin firmar que el cliente debe:
- Firmar off-chain con su clave privada de control.
- Enviar mediante
POST /api/v1/transactions/send.
Este patrón garantiza que la API nunca tiene acceso a las claves privadas de los usuarios.
Autenticación
Actualmente la API no requiere autenticación HTTP estándar (no hay header Authorization). El control de acceso se delega a la blockchain: solo las transacciones firmadas por una EOA autorizada (controlador del DID, o el TA en operaciones especiales) son aceptadas por el smart contract.
Para operaciones especiales como insertFirstDidDocument, la EOA from debe estar previamente autorizada como nodo de onboarding. Si no, la transacción revertirá en cadena.
Formato de respuesta de transacciones
Todos los endpoints POST /contract/... devuelven el mismo objeto:
{
"to": "0x00000000000000000000000000000000000015Be",
"data": "0x<calldata>",
"gasLimit": "0x4c4b40",
"gasPrice": "0xfa0",
"chainId": "0x8131",
"nonce": "0xe",
"value": "0x0",
"from": "0x<EOA_DEL_FIRMANTE>"
}
Todos los campos hexadecimales están codificados como strings con prefijo 0x (formato JSON-RPC de Ethereum).
Códigos de error
La API utiliza el formato estándar:
{
"error": "validation_error",
"error_description": "Field 'vMethodId' must be a base64url-encoded 32 bytes string"
}
| Código HTTP | Significado |
|---|---|
200 OK | Operación exitosa. |
206 Partial Content | Transacción enviada pero el recibo todavía no está disponible. |
400 Bad Request | Cuerpo o parámetros inválidos. |
404 Not Found | DID no encontrado (en endpoints de resolución). |
406 Not Acceptable | Header Accept no soportado. |
500 Internal Server Error | Error inesperado en la API o en la red blockchain. |
Mapa de endpoints
| Endpoint | Tag | Descripción |
|---|---|---|
GET /api/v1/identifiers | Identifiers | Listar DIDs (paginado). |
GET /api/v1/identifiers/{identifier} | Identifiers | Resolver DID Document. |
POST /api/v1/contract/insertFirstDidDocument | DidDocument | Alta inicial de un DID. |
POST /api/v1/contract/insertDidDocument | DidDocument | Sustituir DID Document existente. |
POST /api/v1/contract/updateAlsoKnownAs | DidDocument | Actualizar alsoKnownAs. |
POST /api/v1/contract/updateBaseDocument | DidDocument | Actualizar @context. |
POST /api/v1/contract/addController | Controllers | Añadir controlador. |
POST /api/v1/contract/revokeController | Controllers | Revocar controlador. |
POST /api/v1/contract/addVerificationMethod | Verification Methods | Registrar nueva clave. |
POST /api/v1/contract/revokeVerificationMethod | Verification Methods | Revocar clave. |
POST /api/v1/contract/expireVerificationMethod | Verification Methods | Expirar clave. |
POST /api/v1/contract/rollVerificationMethod | Verification Methods | Rotar clave. |
POST /api/v1/contract/addVerificationRelationship | Verification Relationships | Asociar uso a una clave. |
POST /api/v1/transactions/send | Transactions | Enviar transacción firmada. |
Cada endpoint está documentado en detalle en las siguientes páginas: