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.

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 types that is supported by Dock, the supported type of public key is ed25519.

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

Create DID

Creates a new DID on chain with an auto generated keypair, the controller will be the same as the DID unless otherwise specified. More info about Create DID

POSThttps://api-testnet.dock.io/dids

Body

application/json

Properties of DID

typeenum

dockkeypolygonid

didDID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

controllerDID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

keyTypeKeyType (enum)

Type of public key for DID (NOTE: secp256k1, sr25519 are deprecated)

ed25519bjjsecp256k1sr25519

Response

200400401402409

DID will be created on the network.

Body

application/json

idstring

dataobject

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/dids', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "type": "dock",
      "did": "did:dock:5Gvp...LbFo",
      "controller": "did:dock:5Gvp...LbFo",
      "keyType": "ed25519"
    }),
});
const data = await response.json();

Response

200400401402409

{
  "id": "text"
}

List DIDs

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

List DIDs

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

GEThttps://api-testnet.dock.io/dids

Query parameters

Response

200400

All of a user's DIDs with additional information

Body

application/json

idDID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

didDID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

typeenum

The type of DID, indicating the network or method used.

Example: "dock"

dockkeypolygonid

controllerDID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

credentialCountstring

The number of credentials issued by this DID.

Example: "0"

updatedLaststring (date-time)

The timestamp of the last update to the DID metadata.

Example: "2024-09-26T12:38:10.871Z"

profilenullable object

Additional profile information associated with the DID, such as a public profile or other descriptive metadata.

keyIdstring

The identifier of the key associated with the DID.

Example: "did:dock:5DSMVEPXQ6iQb7msrydkGbd2GSRkWUsLHqwXbertvBaVrabU#keys-1"

jobIdany of

OpenAPI 3.0 null-type refJobId (string)

trustRegistriesarray of object

A list of trust registries associated with this DID.

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/dids', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

[
  {
    "id": "did:dock:xyz",
    "did": "did:dock:xyz",
    "type": "dock",
    "controller": "did:dock:xyz",
    "credentialCount": "0",
    "updatedLast": "2024-09-26T12:38:10.871Z",
    "profile": {
      "name": "My Convener",
      "logo": "text",
      "description": "An ecosystem convener"
    },
    "keyId": "did:dock:5DSMVEPXQ6iQb7msrydkGbd2GSRkWUsLHqwXbertvBaVrabU#keys-1",
    "jobId": null,
    "trustRegistries": [
      {
        "id": "0x592a...c99b",
        "name": "Updated Name",
        "logoUrl": "https://logo.com/ecosystemnew"
      }
    ]
  }
]

Return ecosystems that DID participates in

Returns ecosystems that this DID is a participant in

Returns ecosystems that this DID is a participant in

GEThttps://api-testnet.dock.io/dids/{did}/ecosystems

Path parameters

did*DID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

Response

200400404

Ecosystems list that the DID participates in

Body

application/json

total*integer

list*array of TrustRegistryPublic (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/dids/{did}/ecosystems', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400404

{
  "list": [
    {
      "id": "0xe7e0f253c5f05059904109e33fb63b104edddd7e114a8746a5faf07a944d58aa",
      "slug": "dock-ecosystem-419",
      "convener": "did:dock:5DTD...FKc43",
      "created": "2024-09-26T13:18:51.534Z",
      "name": "Dock Ecosystem",
      "description": "This is my new awesome ecosystem!",
      "logoUrl": "https://logo.dock.io/trust-registry",
      "ecosystemUrl": "https://ecosystem.dock.io",
      "governanceFramework": "This is a markdown document describing my framework",
      "governanceFrameworkVersion": "1.0.0",
      "participantRole": "verifier",
      "participantStatus": "active",
      "participantName": "My Convener",
      "participantLogoUrl": "https://logo.com/participant",
      "participantInfoUrl": "https://participant.dock.io"
    }
  ]
}

Export DID

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

Export DID document and keys

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

POSThttps://api-testnet.dock.io/dids/{did}/export

Path parameters

did*DID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

Body

application/json

A password to encrypt the result with

passwordstring

Response

200400401404

An encrypted Universal Wallet document containing the DID and its keypairs

Body

application/json

@contextarray of string

The context defining the terms used in the credential

idstring

The ID of the credential, typically a DID with a fragment identifier

Example: "did:key:z6LS...Wa19#encrypted-wallet"

typearray of string

The type of the credential, includes VerifiableCredential and other specific types

issuerstring

The issuer of the credential, typically a DID

Example: "did:key:z6LS...Wa19"

issuanceDatestring (date-time)

The date and time the credential was issued

Example: "2024-09-26T12:08:18.803Z"

credentialSubjectobject

The subject of the credential, containing encrypted wallet contents

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/dids/{did}/export', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "password": "astrongpassword"
    }),
});
const data = await response.json();

Response

200400401404

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/wallet/v1"
  ],
  "id": "did:key:z6LS...Wa19#encrypted-wallet",
  "type": [
    "VerifiableCredential",
    "EncryptedWallet"
  ],
  "issuer": "did:key:z6LS...Wa19",
  "issuanceDate": "2024-09-26T12:08:18.803Z",
  "credentialSubject": {
    "id": "did:key:z6LS...Wa19",
    "encryptedWalletContents": {
      "protected": "eyJlbmMiOiJYQzIwUCJ9",
      "recipients": [
        {
          "encrypted_key": "OHwaAnWZThM_lGP-9g_zBSBhbRjOeFEG4LsvTEA5V-5WW63J--Xw4w",
          "header": {
            "kid": "did:key:z6LS...Wa19#z6LS...Wa19",
            "alg": "ECDH-ES+A256KW",
            "epk": {
              "kty": "OKP",
              "crv": "X25519",
              "x": "4xA5LWWdfhLed5AUvHPsDAYaxhsMdV4UBw1kN0As1Hs"
            },
            "apu": "4xA5LWWdfhLed5AUvHPsDAYaxhsMdV4UBw1kN0As1Hs",
            "apv": "ZGlkOmtleTp6NkxTaFZ0VlJiUlA4REFoZm05ODFyQ244WWhNVFBhZzlWNFNNakN..."
          }
        }
      ],
      "iv": "NyMwyU-0QGnaqRVy0u0_Ilae3ETvcZq_",
      "ciphertext": "8MJvLT..._wYO54",
      "tag": "b-fL728NLEZkqz5SEIMI8Q"
    }
  }
}

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 DID

Returns the complete information about the provided "did" which is provided via parameters text box. More info about Get DID

GEThttps://api-testnet.dock.io/dids/{did}

Path parameters

did*DID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

Response

200400404

The DIDDoc

Body

application/json

@contextContext (one of)

JSON-LD context array of strings or single string

Example: "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld"

array of one ofstring

idDID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

authenticationarray of one of

Array of verification methods used for authentication.

assertionMethodarray of one of

Array of verification methods used for assertion.

capabilityInvocationarray of one of

Array of verification methods used for capability invocation.

publicKeyarray of object

Array of public keys associated with the DID document.

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/dids/{did}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400404

{
  "@context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
  "id": "did:dock:xyz",
  "authentication": [
    "did:dock:5DEH...9Luk#keys-1"
  ],
  "assertionMethod": [
    "did:dock:5DEH...9Luk#keys-1"
  ],
  "capabilityInvocation": [
    "did:dock:5DEH...9Luk#keys-1"
  ],
  "publicKey": [
    {
      "id": "did:dock:5DEH...9Luk#keys-1",
      "type": "Sr25519VerificationKey2020",
      "controller": "did:dock:5DEH...9Luk",
      "publicKeyBase58": "Cs8XUWkpkscPhEVCsUAicLqd8pL2MoGqahywfRhbtVEi"
    }
  ]
}

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.

Delete DID

Deletes a provided DID from the blockchain, further attempts to resolve this DID will fail. More info about Delete DID

DELETEhttps://api-testnet.dock.io/dids/{did}

Path parameters

did*DID (string)

DID as fully qualified, typically. did:dock:

Example: "did:dock:xyz"

Response

200400401402404

Will remove DID.

Body

application/json

idstring

dataobject

Request

JavaScriptCurlPython

const response = await fetch('https://api-testnet.dock.io/dids/{did}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

200400401402404

{
  "id": "text"
}