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.

POST /dids REQUEST

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

Parameters

NameInTypeRequiredDescription

did

body

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

false

DID as fully qualified, e.g., did:dock:. The default value of the controller is the did property.

keyType

body

false

Type of public key for DID. The default value of the keyType is sr25519.

Enumerated Values

ParameterValueDesctiprion

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

StatusMeaningDescriptionSchema

200

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.

400

The request was unsuccessful, because of invalid params.

402

Transaction limit reached or upgrade required to proceed

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

GET /dids/{did} REQUEST

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

Parameters

NameInTypeRequiredDescription

did

path

true

Represents a specific DID that uniquely identifies the key resource.

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will return the DID doc.

404

The requested DID was not found.

402

Transaction limit reached or upgrade required to proceed

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

NameInTypeRequiredDescription

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

StatusMeaningDescriptionSchema

200

All of a user's DIDs fully resolved into DID documents.

402

Transaction limit reached or upgrade required to proceed

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

NameInTypeRequiredDescription

did

path

true

Represents a specific DID that uniquely identifies the key resource.

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will remove the DID.

401

The request was unsuccessful, because you don't own the DID.

404

The DID does not exist.

405

The {did} value is blank/empty. Please ensure that the {did} value does exist.

402

Transaction limit reached or upgrade required to proceed

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

NameInTypeRequiredDescription

did

path

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

StatusMeaningDescriptionSchema

200

The request was successful and the DID has been exported.

401

The request was unsuccessful, because you don't own the DID.

404

The DID does not exist.

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

{
}

Last updated