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": "eyJuZXdfa2V5X2hhc2giOiAiMmEzN2I5ZWRmZjc4ZTZjMGQ1ZWY5MDg4OGIyOWZhNjQ5NDk4MDk0YTQ5NzBhNjYwYWRjZDVlMGIzMTYxZTY2ZiIsICJjdXJyZW50X2tleSI6ICItLS0tLUJFR0lOIFBVQkxJQyBLRVktLS0tLVxuTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFdTdab25EWVlFbkNUdlBBOUg4ZU05SnhhUUdIQlxuTXpMZ3hVTW81OFNYb0pLSXp0OTNrUUsvYmh3ZFBuRmFFZlFoaUxCNVZrT0ZnbjJxS2dTY2RJY1hWdz09XG4tLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0iLCAibmV4dF9rZXlfaGFzaCI6ICJjY2NhNmMxMWNmYTQwZjI2Njk2OGY2YTcxYmJhNDk1YmM3M2U5N2Q4ODJlYjc0NTIzNzg0NzY5ZDQzMTc1Y2Q1IiwgIm9wZXJhdGlvbiI6ICJkaWRfYWRkIiwgImRpZF9hZGRyZXNzIjogImRpZDppZGluOmFmYjdiYTg4Yzc2ZWRiZGE1NWMzNDRiNzBhZTBjZjA1NTZkNzcwZWMyNTY4MjBkNzE4NTAwMGRlMzk1MzkxYjUiLCAibm9uY2UiOiAxfQ==",
    "signature": "MEUCIQCfZqZodAu7pTgb9xLHdi+DWTrwbCjI4z18RXAQFcXp0AIgf3VyAP86Yr6gMqUiMg97YJRx67ELwlaKFhh9Bolj3cY="
}

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_add",
    "did_address": "did:idin:afb7ba88c76edbda55c344b70ae0cf0556d770ec256820d7185000de395391b5",
    "current_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEu7ZonDYYEnCTvPA9H8eM9JxaQGHB\nMzLgxUMo58SXoJKIzt93kQK/bhwdPnFaEfQhiLB5VkOFgn2qKgScdIcXVw==\n-----END PUBLIC KEY-----",
    "next_key_hash": "ccca6c11cfa40f266968f6a71bba495bc73e97d882eb74523784769d43175cd5",
    "new_key_hash": "2a37b9edff78e6c0d5ef90888b29fa649498094a4970a660adcd5e0b3161e66f",
    "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