DID

Manage DID operation using DID APIs

Please generate access token before proceeding. Once you generated the access_token, you can pass this token as bearer authorization token in the header for all APIs.

Note: Some of these APIs are on-chain APIs which means they need network fee to successfully execute, so make sure that your application wallet address has $hid tokens. Read network fee section for more details.

Entity Studio SSI API base URL: https://api.entity.hypersign.id

There are 3 steps involved in DID creation:

• Generate a DID Document: Generate the data structure of the DID document.

• Sign a DID Document (optional): Sign the DID Document using verification method.

• Register a DID Document (optional) : Registers the signed DID Document on the blockchain network.

Note: You can choose not to register a DID on blockchain, in that case, the DID is concidered as private DID. We support Ed25519VerificationKey2020 for private DIDs. Kindly read difference between private and public DID in this section.

Create a DID

Generates the a new DID and DID Document.

post

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringOptional

Bearer <access_token>

OriginstringOptional

Origin as you set in application cors

Body

application/json

namespacestringRequired

Namespace to be added in did.

Example: testnet

methodSpecificIdstringOptional

MethodSpecificId to be added in did

Example: 0x19d73aeeBcc6FEf2d0342375090401301Fe9663F

Responses

201

DID Created

application/json

400

Error occured at the time of creating did

application/json

409

Duplicate key error

application/json

post

/api/v1/did/create

HTTPcURLJavaScriptPython

POST /api/v1/did/create HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 340

{
  "namespace": "testnet",
  "methodSpecificId": "0x19d73aeeBcc6FEf2d0342375090401301Fe9663F",
  "options": {
    "keyType": "Ed25519VerificationKey2020",
    "chainId": "0x1",
    "publicKey": "z76tzt4XCb6FNqC3CPZvsxRfEDX5HHQc2VPux4DeZYndW",
    "walletAddress": "0x01978e553Df0C54A63e2E063DFFe71c688d91C76",
    "verificationRelationships": [
      "assertionMethod",
      "authentication"
    ]
  }
}

{
  "did": "did:hid:namespace:.......................",
  "registrationStatus": "COMPLETED/PROCESSING",
  "metaData": {
    "didDocument": {
      "@context": [
        "https://www.w3.org/ns/did/v1"
      ],
      "id": "did:hid:method:......",
      "controller": [
        "did:hid:method:......"
      ],
      "alsoKnownAs": [
        "did:hid:method:......"
      ],
      "verificationMethod": [
        {
          "id": "did:hid:testnet:z28ScfSszr2zi2Bd7qmNE4mfHX5j8nCwx4DBF6nAUHu4p#key-1",
          "type": "EcdsaSecp256k1RecoveryMethod2020",
          "controller": "did:hid:method:..............",
          "blockchainAccountId": "eip155:1:0x19d73aeeBcc6FEf2d0342375090401301Fe9663F"
        }
      ],
      "authentication": [
        "did:hid:method:......"
      ],
      "assertionMethod": [
        "did:hid:method:......"
      ],
      "keyAgreement": [
        "did:hid:method:......"
      ],
      "capabilityInvocation": [
        "did:hid:method:......"
      ],
      "capabilityDelegation": [
        "did:hid:method:......"
      ],
      "service": [
        {
          "id": "did:hid:testnet:z23dCariJNNpMNca86EtVZVvrLpn61isd86fWVyWa8Jkm#linked-domain",
          "type": "LinkedDomains",
          "serviceEndpoint": "https://stage.hypermine.in/studioserver/api/v1/org/did:hid:testnet:......................"
        }
      ]
    }
  }
}

Request Body Parameters

• Namespace: DID name space. Possible value is testnet

Optional Parameters

• MethodSpecificId: Custom Id string which you want to attach with the DID. Please read did:hid method spec for details about possible format.

• Options.keyTypes: We support Ed25519VerificationKey2020, EcdsaSecp256k1RecoveryMethod2020 verification method key types. So only these two are possible values. Read the full specification here.

• Options.publicKey: Please pass the options.publickey property only for Ed25519VerificationKey2020 verification method key type. For EcdsaSecp256k1RecoveryMethod2020 , this property can be kept blank. Its value would be publickey (in multi base format)

• Options.walletAddress: Please pass options.walletAddress for keyType EcdsaSecp256k1RecoveryMethod2020

• Options.chainId: ChainId in HEX format. For example for Etheruem main net, the chain id would be 0x1. This property is only required for keytype EcdsaSecp256k1RecoveryMethod2020

Note: If no optional parameters are provided then, did will be created of verification key method type Ed25519VerificationKey2020

Note: If you want to create DID for blockchain wallet addresses like EVM wallets, Cosmos wallets, you should use keyType as . Read EcdsaSecp256k1RecoveryMethod2020

Register a DID

Registers a Signed DID Document in DID registry. The Gas fee (network fee) for this DID registration will be done by applications' walletAddress.

post

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringOptional

Bearer <access_token>

OriginstringOptional

Origin as you set in application cors

Body

application/json

verificationMethodIdstringRequired

Verification Method id for did registration

Example: did:hid:testnet:........#key-${idx}

clientSpecstringOptional

IClientSpec 'eth-personalSign' or 'cosmos-ADR036'

Example: eth-personalSign

signaturestringOptional

Signature for clientSpec

Example: afafljagahgp9agjagknaglkj/kagka=

Responses

201

DID Registred

application/json

400

Error occured at the time of creating did

application/json

post

/api/v1/did/register

HTTPcURLJavaScriptPython

POST /api/v1/did/register HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1028

{
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:hid:method:......",
    "controller": [
      "did:hid:method:......"
    ],
    "alsoKnownAs": [
      "did:hid:method:......"
    ],
    "verificationMethod": [
      {
        "id": "did:hid:testnet:z28ScfSszr2zi2Bd7qmNE4mfHX5j8nCwx4DBF6nAUHu4p#key-1",
        "type": "EcdsaSecp256k1RecoveryMethod2020",
        "controller": "did:hid:method:..............",
        "blockchainAccountId": "eip155:1:0x19d73aeeBcc6FEf2d0342375090401301Fe9663F"
      }
    ],
    "authentication": [
      "did:hid:method:......"
    ],
    "assertionMethod": [
      "did:hid:method:......"
    ],
    "keyAgreement": [
      "did:hid:method:......"
    ],
    "capabilityInvocation": [
      "did:hid:method:......"
    ],
    "capabilityDelegation": [
      "did:hid:method:......"
    ],
    "service": [
      {
        "id": "did:hid:testnet:z23dCariJNNpMNca86EtVZVvrLpn61isd86fWVyWa8Jkm#linked-domain",
        "type": "LinkedDomains",
        "serviceEndpoint": "https://stage.hypermine.in/studioserver/api/v1/org/did:hid:testnet:......................"
      }
    ]
  },
  "verificationMethodId": "did:hid:testnet:........#key-${idx}",
  "clientSpec": "eth-personalSign",
  "signature": "afafljagahgp9agjagknaglkj/kagka="
}

{
  "did": "did:hid:namespace:.......................",
  "registrationStatus": "COMPLETED/PROCESSING",
  "metaData": {
    "didDocument": {
      "@context": [
        "https://www.w3.org/ns/did/v1"
      ],
      "id": "did:hid:method:......",
      "controller": [
        "did:hid:method:......"
      ],
      "alsoKnownAs": [
        "did:hid:method:......"
      ],
      "verificationMethod": [
        {
          "id": "did:hid:testnet:z28ScfSszr2zi2Bd7qmNE4mfHX5j8nCwx4DBF6nAUHu4p#key-1",
          "type": "EcdsaSecp256k1RecoveryMethod2020",
          "controller": "did:hid:method:..............",
          "blockchainAccountId": "eip155:1:0x19d73aeeBcc6FEf2d0342375090401301Fe9663F"
        }
      ],
      "authentication": [
        "did:hid:method:......"
      ],
      "assertionMethod": [
        "did:hid:method:......"
      ],
      "keyAgreement": [
        "did:hid:method:......"
      ],
      "capabilityInvocation": [
        "did:hid:method:......"
      ],
      "capabilityDelegation": [
        "did:hid:method:......"
      ],
      "service": [
        {
          "id": "did:hid:testnet:z23dCariJNNpMNca86EtVZVvrLpn61isd86fWVyWa8Jkm#linked-domain",
          "type": "LinkedDomains",
          "serviceEndpoint": "https://stage.hypermine.in/studioserver/api/v1/org/did:hid:testnet:......................"
        }
      ]
    }
  },
  "transactionHash": "XYAIFLKFLKHSLFHKLAOHFOAIHG.........."
}

Request Parameters

• didDocument : DID documented generated using /api1/v1/did/create API

• verificationMethodId : Verification Method id of referred verification method in the didDocument

Optional Parameters

• clientSpec : Wallet specifications which are used to sign the didDocument string. Use eth-personalSign for Metamask and cosmos-ADR036 for Keplr wallet. Learn more about client specifications here.

• signature: If didDocument is signed using client wallets (Metamask or Keply) then pass the signature hex string.

Note: Read how to use Metamask to create Hypersign DID.

Resolve a DID

Given a DID Id (example: did:hid:testnet:0x123123123123), this API will resolve the corresponding DID Document from the DID registry (or Hypersign Blockchain).

get

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

didstringRequired

Header parameters

AuthorizationstringOptional

Bearer <access_token>

OriginstringOptional

Origin as you set in application cors

Responses

200

DID Resolved

application/json

get

/api/v1/did/resolve/{did}

HTTPcURLJavaScriptPython

GET /api/v1/did/resolve/{did} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

DID Resolved

{
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:hid:method:......",
    "controller": [
      "did:hid:method:......"
    ],
    "alsoKnownAs": [
      "did:hid:method:......"
    ],
    "verificationMethod": [
      {
        "id": "did:hid:testnet:z28ScfSszr2zi2Bd7qmNE4mfHX5j8nCwx4DBF6nAUHu4p#key-1",
        "type": "EcdsaSecp256k1RecoveryMethod2020",
        "controller": "did:hid:method:..............",
        "blockchainAccountId": "eip155:1:0x19d73aeeBcc6FEf2d0342375090401301Fe9663F"
      }
    ],
    "authentication": [
      "did:hid:method:......"
    ],
    "assertionMethod": [
      "did:hid:method:......"
    ],
    "keyAgreement": [
      "did:hid:method:......"
    ],
    "capabilityInvocation": [
      "did:hid:method:......"
    ],
    "capabilityDelegation": [
      "did:hid:method:......"
    ],
    "service": [
      {
        "id": "did:hid:testnet:z23dCariJNNpMNca86EtVZVvrLpn61isd86fWVyWa8Jkm#linked-domain",
        "type": "LinkedDomains",
        "serviceEndpoint": "https://stage.hypermine.in/studioserver/api/v1/org/did:hid:testnet:......................"
      }
    ]
  },
  "didDocumentMetadata": {
    "created": "2023-01-23T13:45:17Z",
    "updated": "2023-01-23T13:45:17Z",
    "deactivated": "false",
    "versionId": "095A65E4D2F9CA2AACE0D17A28883A0E5DDC1BBE1C9BF9D............."
  }
}

Fetch all DIDs for your apps

get

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pagenumberOptional

Page value

Default: 1

limitnumberOptional

Fetch limited list of data

Default: 10

Header parameters

AuthorizationstringOptional

Bearer <access_token>

OriginstringOptional

Origin as you set in application cors

Responses

200

DID List

application/json

404

Error in finding resource

application/json

get

/api/v1/did

HTTPcURLJavaScriptPython

GET /api/v1/did HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "totalCount": 12,
    "data": [
      "did:hid:testnet:............"
    ]
  }
]

Update a DID

Update a DIDDocument

patch

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringOptional

Bearer <access_token>

OriginstringOptional

Origin as you set in application cors

Body

application/json

deactivatebooleanRequired

Field to check if to deactivate did or to update it

Example: false

verificationMethodIdstringRequired

Verification Method id for did updation

Example: did:hid:testnet:........#key-${idx}

clientSpecstringOptional

IClientSpec 'eth-personalSign' or 'cosmos-ADR036'

Example: eth-personalSign

signaturestringOptional

Signature for clientSpec

Example: afafljagahgp9agjagknaglkj/kagka=

Responses

200

DID Updated

application/json

400

Invalid didDoc

application/json

404

Resource not found

application/json

patch

/api/v1/did

HTTPcURLJavaScriptPython

PATCH /api/v1/did HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1047

{
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:hid:method:......",
    "controller": [
      "did:hid:method:......"
    ],
    "alsoKnownAs": [
      "did:hid:method:......"
    ],
    "verificationMethod": [
      {
        "id": "did:hid:testnet:z28ScfSszr2zi2Bd7qmNE4mfHX5j8nCwx4DBF6nAUHu4p#key-1",
        "type": "EcdsaSecp256k1RecoveryMethod2020",
        "controller": "did:hid:method:..............",
        "blockchainAccountId": "eip155:1:0x19d73aeeBcc6FEf2d0342375090401301Fe9663F"
      }
    ],
    "authentication": [
      "did:hid:method:......"
    ],
    "assertionMethod": [
      "did:hid:method:......"
    ],
    "keyAgreement": [
      "did:hid:method:......"
    ],
    "capabilityInvocation": [
      "did:hid:method:......"
    ],
    "capabilityDelegation": [
      "did:hid:method:......"
    ],
    "service": [
      {
        "id": "did:hid:testnet:z23dCariJNNpMNca86EtVZVvrLpn61isd86fWVyWa8Jkm#linked-domain",
        "type": "LinkedDomains",
        "serviceEndpoint": "https://stage.hypermine.in/studioserver/api/v1/org/did:hid:testnet:......................"
      }
    ]
  },
  "deactivate": false,
  "verificationMethodId": "did:hid:testnet:........#key-${idx}",
  "clientSpec": "eth-personalSign",
  "signature": "afafljagahgp9agjagknaglkj/kagka="
}

{
  "transactionHash": "XYAIFLKFLKHSLFHKLAOHFOAIHG.........."
}

Request Parameters

• didDocument : DID documented to be updated

• verificationMethodId : Verification Method id of referred verification method in the didDocument

• deactivate : true is you want to deactivate this DID, false otherwise.

Optional Parameters

• clientSpec : Wallet specifications which are used to sign the didDocument string. Use eth-personalSign for Metamask and cosmos-ADR036 for Keplr wallet. Learn more about client specifications here.

• signature: If didDocument is signed using client wallets (Metamask or Keply) then pass the signature hex string.