DIDs

DID stands for Decentralized IDentifiers. DIDs are meant to be globally unique identifiers that allow their owner to prove cryptographic control over them. A DID identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the DID decides that it identifies.

DIDs in Dock are created by choosing a 32-byte unique (on Dock chain) identifier along with a public key. You can update and delete a DID as well as list all DIDs. DID is identified by a unique, random key.

For a detailed example of the DIDs workflow. Please refer here.

Currently a DID can have only one key at a time as a controller, soon we will support multiple keys per DID.

Endpoints

POST /dids GET /dids/{did} GET /dids DELETE /dids/{did} POST /dids/{did}/export

Create DID

A DID, a public key, and a controller are required to create a new DID. The controller is both the owner of the public key and a DID. The DID can be created using an auto-generated keypair, and the controller will be the same as the DID unless otherwise specified. The DID and public key have no cryptographic relation.

It is important to have a public key of one of its three supported types. Dock supports 3 types of public keys: sr25519, ed25519, and secp256k1.

Parameters

Name	In	Type	Required	Description
did	body	DIDDock	false	DID as fully qualified, e.g., did:dock:. Default value will is a randomly generated DID.
type	body	string	false	Specifies the DID method to for the generated DID. Supported options are key, polygonid and dock (default).
controller	body	DIDDock	false	DID as fully qualified, e.g., did:dock:. The default value of the controller is the did property.
keyType	body	KeyType	false	Type of public key for DID. The default value of the keyType is sr25519.

Enumerated Values

Parameter	Value	Desctiprion
keyType	sr25519 or ed25519 or secp256k1 or bjj	keyType signature variants.
type	dock or key or polyginid	which DID method to generate

When creating a Polygon ID DID, be sure to set the `keyType` field to `bjj`.

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful and will try to create DID. NOTE: DID does not exist on network until the job identified in the response is complete.	JobStartedResult
400	Bad Request	The request was unsuccessful, because of invalid params.	Error
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

POST /dids REQUEST PAYLOAD

{
  "type": "dock",
  "keyType": "ed25519"
}

POST /dids REQUEST CURL

curl --location --request POST 'https://api.dock.io/dids' \
--header 'DOCK-API-TOKEN: API_KEY' \
--data-raw '{
  "type": "dock",
  "keyType": "ed25519"
}'

200 Response

{
  "id": "926",
  "data": {
    "did": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA",
    "hexDid": "0x3d7129a4d915e8f864c4bf4f4bcbdb67cde87e9bbcec06cb3baefd5b31812c03",
    "controller": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA"
  }
}

Get DID

When a DID is provided in the path, the API will attempt to resolve that DID into a DID document. This document contains the public keys and more information relating to that DID, check the identity foundation did configuration document to learn more.

The API supports resolving many DID methods, some examples are:

• did:dock:5CEdyZkZnALDdCAp7crTRiaCq6KViprTM6kHUQCD8X6VqGPW - resolves through the Dock blockchain

• did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd - the public key is embedded in the DID

Parameters

Name	In	Type	Required	Description
did	path	DIDDock	true	Represents a specific DID that uniquely identifies the key resource.

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful and will return the DID doc.
404	Not Found	The requested DID was not found.	Error
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

GET /dids/{did} REQUEST

curl --location --request GET 'https://api.dock.io/dids/did:dock:xyz' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

200 Response

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN",
  "authentication": [
    "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN#keys-1"
  ],
  "assertionMethod": [
    "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN#keys-1"
  ],
  "publicKey": [
    {
      "id": "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN#keys-1",
      "type": "Sr25519VerificationKey2020",
      "controller": "did:dock:5EEepQGeAeWnYgV8DWj5pH7pjHqrP2ZN2oBiE6ND2ZHA1dyN",
      "publicKeyBase58": "ZY7vx2Jg1NSpEyrfGpDm7mRxNZyoYtbjjCjhHbhPtzM"
    }
  ]
}

List DIDs

Return a list of all DIDs that your user account controls as fully resolved DID documents.

Parameters

Name	In	Type	Required	Description
offset	query	integer	false	How many items to offset by for pagination
limit	query	integer	false	How many items to return at one time (max 64)

Responses

Status	Meaning	Description	Schema
200	OK	All of a user's DIDs fully resolved into DID documents.	DIDDock
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

GET /dids REQUEST

curl --location --request GET 'https://api.dock.io/dids' \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

200 Response

[
  {
    "@context": "https://www.w3.org/ns/did/v1",
    "id": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA",
    "authentication": [
      "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA#keys-1"
    ],
    "assertionMethod": [
      "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA#keys-1"
    ],
    "publicKey": [
      {
        "id": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA#keys-1",
        "type": "Sr25519VerificationKey2020",
        "controller": "did:dock:5DTGPqE2qYncxoDjrEWKhcTnn6hfsN24F7YZWSjGVUxgBgHA",
        "publicKeyBase58": "4vm85LvBvhro1N9u4dfKWEyTayXojrTJbJCmzSJixK6L"
      }
    ]
  }
]

Delete DID

Deletes a DID and its metadata from the blockchain and our platform. This will also delete the associated keypair from the key management system meaning that you cannot sign messages or credentials with it after this operation. The DID will no longer be able to be resolved. This operation is not reversible.

Parameters

Name	In	Type	Required	Description
did	path	DID	true	Represents a specific DID that uniquely identifies the key resource.

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful and will remove the DID.	JobId
401	Unauthorized	The request was unsuccessful, because you don't own the DID.	Error
404	Not Found	The DID does not exist.	Error
405	Method not Allowed	The {did} value is blank/empty. Please ensure that the {did} value does exist.	Error
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

DELETE /dids/{did} REQUEST

curl --location --request DELETE https://api.dock.io/dids/{did} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    }'

200 Response

{
  "id": "928",
  "data": {
    "deleted": true
  }
}

Export DID

Exports the DID document and keys as an encrypted Universal Wallet JSON-LD document

Parameters

Name	In	Type	Required	Description
did	path	DID	true	Represents a specific DID that uniquely identifies the key resource.
password	body	string	true	A password to encrypt the JSON-LD payload with

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful and the DID has been exported.
401	Unauthorized	The request was unsuccessful, because you don't own the DID.	Error
404	Not Found	The DID does not exist.	Error

POST /dids/{did}/export REQUEST

curl --location --request POST https://api.dock.io/dids/{did}/export \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "password": "aStr0ngP@ssw0rd"
    }'

200 Response

{
}