DID API

Overview

The DID API provides a collection of HTTP request methods that underpin IDIN blockchain's functionality. The DID API includes HTTP methods for registration of a Decentralized Identifier (DID), key series management and resetter management. HTTP requests to the IDIN server must be in the JSON format with the following two attributes:

  1. "message": The request message that is encoded in the Base64 format.

  2. "signature": The signature of the Base64-encoded request message. The encoded message is signed by a private key.

{
"message": "ewogICAgIm9wZXJhdGlvbiI6ICJkaWRfcmVnaXN0ZXJfcmVzZXR0ZXJzIiwKICAgICJkaWRfYWRkcmVzcyI6ICJkaWQ6aWRpbjo5Y2QxOWQ0Y2JhYjljYTFkNmY0YzZhNGI5MTE3ZmI4OTA0ZjI1MGI0NzMwN2NmNGY0ODQ0MjRmNDRlMGM4MzcwIiwKICAgICJjdXJyZW50X2tleSI6ICItLS0tLUJFR0lOIFBVQkxJQyBLRVktLS0tLVxuTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFZVI4TmhRZUhQVDdsMXlNeXZrWk1hY1BwaWJqSFxuN21wNUlSeU8ySjJrdUU5N2gvZnp1MWMvN0RGc08yM3FVTjYvT2V6WWdsTUVrb1ZvNU9iMWI2azUzQT09XG4tLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0iLAogICAgIm5leHRfa2V5X2hhc2giOiAiYTE4Yjc5MGE5MjY4M2FkMDBkMzU2MmRlMzg1Y2E5ZTA3ZDIwYTcyOTgwOWM3ODJlNzI0MTJmNTdkZDg0NzEwNSIKICAgICJub25jZSI6IDEKfQ==",
"signature": "OTI3MzgyNDgzNTQ3NTU5ODMyNTM1NzYwMDc2MTEwNzYwMTUzMjAzMzQ2NzQ5MDU4NzIwMzM4ODUzNjc4OTE2MTI2NzA2NzQyODgyMDcsIDQ1MjE2NzEwMzM3MjI5NjEzOTc3MjYxMzY2MjUwODYxOTA5MzY2MDU1MDg2Mjk0NzEyMDAwMTU3MjU4ODYxNTQ3ODUzNDc3NTY2ODQw"
}

There are several types of requests, such as registering a new DID address and adding a new key series to a DID. The request messages are also in the JSON format with a number of attributes depending on the request types. With the exception of registering a new DID, all request messages contain the following five attributes:

  1. "operation": The request method's name that tells the server to execute the right operation.

  2. "did_address": The DID address of which a key series is used to sign and verify the request.

  3. "current_key": The public key in the PEM format for verifying the request's signature. It is the current public key in the key series and is the public key pair of the private key that signs the request.

  4. "next_key_hash": The SHA-256 hash of the next public key in PEM format in the key series.

  5. "nonce": The request nonce that is bound to the given DID address. It starts at one and then increases by one for every request, and as a result it counts to the total number of requests that the DID has made.

The code snippet below shows an example request message for revoking the current set of resetters.

{
"operation": "did_register_resetters",
"did_address": "did:idin:9cd19d4cbab9ca1d6f4c6a4b9117fb8904f250b47307cf4f484424f44e0c8370",
"current_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEeR8NhQeHPT7l1yMyvkZMacPpibjH\n7mp5IRyO2J2kuE97h/fzu1c/7DFsO23qUN6/OezYglMEkoVo5Ob1b6k53A==\n-----END PUBLIC KEY-----",
"next_key_hash": "a18b790a92683ad00d3562de385ca9e07d20a729809c782e72412f57dd847105"
"nonce": 1
}

The DID registration request is the only request method that does not contain "did_address" and"nonce" since these two attributes must be bound to a DID.

When the server receives a HTTP request from a client, the server first decodes the request message ("message"), check whether all attributes are valid and then uses the verifying public key ("current_key") to verify the request's signature ("signature"). If "did_address" is in the request message, the server will also check whether the "current_key" is a valid current public key in any of the DID's key series.

DID Requests

The table below summarizes all DID-related HTTP requests to the IDIN server.

Request Method

Description

HTTP Method

did_register

Register a new DID address.

POST

did_add

Add a new key series to a DID.

POST

did_revoke

Revoke a key series from a DID.

DELETE

did_register_resetters

Register a new set of resetters for a DID.

POST

did_revoke_resetters

Revoke the current set of resetters of a DID.

DELETE

did_resetter_approve

Approve a resetter request.

POST

Get the current nonce of a DID.

GET