Verifiable Credential

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.

Issue a verifiable credential

An issuer may issue a verifiable credential to a subject using this API. The credential document is signed by issuer's identity key and its status is registered on the blockchain.

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

POST/api/v1/credential/issue

Authorization

Authorization

Header parameters

Body

application/json

schemaIdstring

schemaId for credential Schema

subjectDid*string

holder did of the credential

issuerDid*string

issuerDid of the credential

expirationDate*string

Date in ISOString format

Example: "2027-12-10T18:30:00.000Z"

fields*object

Credential Data fields

namespace*string

Namespace to be added in vcId.

Example: "testnet"

verificationMethodId*string

Verification Method id for did updation

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

persist*boolean

Persist in edv

Example: "true"

Response

201400404

Credential Created

Body

application/json

credentialDocument*all of

Credential doc

credentialStatus*all of

Status detail of credential

persist*boolean

Define whether to store cred or ust store its meta

Example: true

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/credential/issue', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "subjectDid": "text",
      "issuerDid": "text",
      "expirationDate": "2027-12-10T18:30:00.000Z",
      "fields": {
        "name": "Random name"
      },
      "namespace": "testnet",
      "verificationMethodId": "did:hid:testnet:........#key-${idx}",
      "persist": "true"
    }),
});
const data = await response.json();

Response

201400404

{
  "credentialDocument": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      {
        "hs": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/schema/sch:hid:testnet:...........:1.0:"
      },
      {
        "name": "hs:name"
      },
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "vc:hid:testnet:......",
    "type": [
      "VerifiableCredential",
      "nameschema"
    ],
    "expirationDate": "2027-12-10T18:30:00Z",
    "issuanceDate": "2027-12-10T18:30:00Z",
    "issuer": "did:hid:testnet:..........",
    "credentialSubject": {
      "id": "did:hid:testnet:..............."
    },
    "credentialSchema": {
      "id": "sch:hid:testnet:...............",
      "type": "JsonSchemaValidator2018"
    },
    "credentialStatus": {
      "id": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/credential/vc:hid:testnet:...............",
      "type": "CredentialStatusList2017"
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2023-01-25T17:01:02Z",
      "verificationMethod": "did:hid:testnet:...............#key-${id}",
      "proofPurpose": "assertionMethod",
      "proofValue": "z5LairjrBYkc5FtP.......................EXFHm37aDvcMtCvnYfmvQ"
    }
  },
  "credentialStatus": {
    "claim": {
      "id": "vc:hid:testnet:................",
      "currentStatus": "vc:hid:testnet:................",
      "statusReason": "Credential is active"
    },
    "issuer": "did:hid:testnet:..............",
    "issuanceDate": "2023-01-25T16:59:21Z",
    "expirationDate": "2023-01-25T16:59:21Z",
    "credentialHash": "ae93886f2a............3f6d1c6ae4..........393d43730"
  },
  "persist": true
}

NOTE: A developer may choose to store the verifiable credential in application's data vault securely or they may not to. Pass true for request body property persist to store the credential document, false otherwise.

Verify an issued verifiable credential document

A signed verifiable credential must has signature of the issuer. Any one may verify an issued credential document. The verification result state the following facts:

• This document was issued by intended issuer

• This document have not been tampered

• This document have not been revoked

POST/api/v1/credential/verify

Authorization

Authorization

Header parameters

Body

application/json

credentialDocument*all of

credential document

Response

200400404

verification result of credential

Body

application/json

verified*boolean

result of credential verification

results*array of Result (object)

Verification detail of proof

statusResult*all of

Verification result

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/credential/verify', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "credentialDocument": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          {
            "hs": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/schema/sch:hid:testnet:...........:1.0:"
          },
          {
            "name": "hs:name"
          },
          "https://w3id.org/security/suites/ed25519-2020/v1"
        ],
        "id": "vc:hid:testnet:......",
        "type": [
          "VerifiableCredential",
          "nameschema"
        ],
        "expirationDate": "2027-12-10T18:30:00Z",
        "issuanceDate": "2027-12-10T18:30:00Z",
        "issuer": "did:hid:testnet:..........",
        "credentialSubject": {
          "id": "did:hid:testnet:..............."
        },
        "credentialSchema": {
          "id": "sch:hid:testnet:...............",
          "type": "JsonSchemaValidator2018"
        },
        "credentialStatus": {
          "id": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/credential/vc:hid:testnet:...............",
          "type": "CredentialStatusList2017"
        },
        "proof": {
          "type": "Ed25519Signature2020",
          "created": "2023-01-25T17:01:02Z",
          "verificationMethod": "did:hid:testnet:...............#key-${id}",
          "proofPurpose": "assertionMethod",
          "proofValue": "z5LairjrBYkc5FtP.......................EXFHm37aDvcMtCvnYfmvQ"
        }
      }
    }),
});
const data = await response.json();

Response

200400404

{
  "verified": false,
  "results": [
    {
      "proof": {
        "type": "Ed25519Signature2020",
        "created": "2023-01-25T17:01:02Z",
        "verificationMethod": "did:hid:testnet:...............#key-${id}",
        "proofPurpose": "assertionMethod",
        "proofValue": "z5LairjrBYkc5FtP.......................EXFHm37aDvcMtCvnYfmvQ",
        "Context": [
          "https://www.w3.org/2018/credentials/v1",
          {
            "hs": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/schema/sch:hid:testnet:z3KX4ZqoizKTaED645aV4aE8dBbnSpmQYe3xfzVBJadPY:1.0:"
          },
          {
            "name": "hs:name"
          },
          "https://w3id.org/security/suites/ed25519-2020/v1"
        ]
      },
      "verified": true,
      "verificationMethod": {
        "id": "did:hid:testnet:................................#key-${id}",
        "type": "Ed25519VerificationKey2020",
        "controller": "did:hid:method:..............",
        "publicKeyMultibase": "z28ScfSszr.............j8nCwx4DBF6nAUHu4p"
      },
      "purposeResult": {
        "valid": true
      }
    }
  ],
  "statusResult": {
    "verified": true
  }
}

NOTE: Verifying a credential document is different than verifying a verifiable presentation. Verification result of later, also states that "Only intended subject holds this document and not one else".

Fetch a verifiable credential and/or its status by Id

GET/api/v1/credential/{credentialId}

Authorization

Authorization

Path parameters

credentialId*string

Query parameters

Header parameters

Response

200404

Resolved credential detail

Body

application/json

credentialDocumentall of

credential document

credentialStatus*all of

status of the credential

persist*boolean

return credentialDocument if persist is set to true at the time of issuing credential

Example: true

retrieveCredential*boolean

If set true then return credential Document also

Example: true

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/credential/{credentialId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200404

{
  "credentialDocument": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      {
        "hs": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/schema/sch:hid:testnet:...........:1.0:"
      },
      {
        "name": "hs:name"
      },
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "vc:hid:testnet:......",
    "type": [
      "VerifiableCredential",
      "nameschema"
    ],
    "expirationDate": "2027-12-10T18:30:00Z",
    "issuanceDate": "2027-12-10T18:30:00Z",
    "issuer": "did:hid:testnet:..........",
    "credentialSubject": {
      "id": "did:hid:testnet:..............."
    },
    "credentialSchema": {
      "id": "sch:hid:testnet:...............",
      "type": "JsonSchemaValidator2018"
    },
    "credentialStatus": {
      "id": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/credential/vc:hid:testnet:...............",
      "type": "CredentialStatusList2017"
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2023-01-25T17:01:02Z",
      "verificationMethod": "did:hid:testnet:...............#key-${id}",
      "proofPurpose": "assertionMethod",
      "proofValue": "z5LairjrBYkc5FtP.......................EXFHm37aDvcMtCvnYfmvQ"
    }
  },
  "credentialStatus": {
    "claim": {
      "id": "vc:hid:testnet:................",
      "currentStatus": "vc:hid:testnet:................",
      "statusReason": "Credential is active"
    },
    "issuer": "did:hid:testnet:..............",
    "issuanceDate": "2023-01-25T16:59:21Z",
    "expirationDate": "2023-01-25T16:59:21Z",
    "credentialHash": "ae93886f2a............3f6d1c6ae4..........393d43730",
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2023-01-25T17:01:02Z",
      "verificationMethod": "did:hid:testnet:...............#key-${id}",
      "proofPurpose": "assertionMethod",
      "proofValue": "z5LairjrBYkc5FtP.......................EXFHm37aDvcMtCvnYfmvQ",
      "updated": "2023-01-25T17:01:02Z"
    }
  },
  "persist": true,
  "retrieveCredential": true
}

Pass false value to parameter retrieveCredential to only retrieve status of the credential

Fetch list of verifiable credentials

GET/api/v1/credential

Authorization

Authorization

Query parameters

Header parameters

Response

200404

List of credentials

Body

application/json

totalCount*number

totalCount

Example: 12

data*array of Credential (object)

data

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/credential', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200404

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

Update credential status of a verifiable credential

PATCH/api/v1/credential/status/{credentialId}

Authorization

Authorization

Path parameters

credentialId*string

Header parameters

Body

application/json

namespace*string

Namespace to be added in vcId.

Example: "testnet"

status*string

Credential status

Example: "LIVE / SUSPEND / REVOKE"

statusReason*string

Credential status Reason

Example: "Reason"

issuerDid*string

issuerDid of the credential

verificationMethodId*string

Verification Method id for did updation

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

Response

200400404

Credential Updated

Body

application/json

credentialDocumentall of

credential document

credentialStatus*all of

status of the credential

persist*boolean

return credentialDocument if persist is set to true at the time of issuing credential

Example: true

retrieveCredential*boolean

If set true then return credential Document also

Example: true

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/credential/status/{credentialId}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "namespace": "testnet",
      "status": "LIVE / SUSPEND / REVOKE",
      "statusReason": "Reason",
      "issuerDid": "text",
      "verificationMethodId": "did:hid:testnet:........#key-${idx}"
    }),
});
const data = await response.json();

Response

200400404

{
  "credentialDocument": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      {
        "hs": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/schema/sch:hid:testnet:...........:1.0:"
      },
      {
        "name": "hs:name"
      },
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "vc:hid:testnet:......",
    "type": [
      "VerifiableCredential",
      "nameschema"
    ],
    "expirationDate": "2027-12-10T18:30:00Z",
    "issuanceDate": "2027-12-10T18:30:00Z",
    "issuer": "did:hid:testnet:..........",
    "credentialSubject": {
      "id": "did:hid:testnet:..............."
    },
    "credentialSchema": {
      "id": "sch:hid:testnet:...............",
      "type": "JsonSchemaValidator2018"
    },
    "credentialStatus": {
      "id": "https://api.jagrat.hypersign.id/hypersign-protocol/hidnode/ssi/credential/vc:hid:testnet:...............",
      "type": "CredentialStatusList2017"
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2023-01-25T17:01:02Z",
      "verificationMethod": "did:hid:testnet:...............#key-${id}",
      "proofPurpose": "assertionMethod",
      "proofValue": "z5LairjrBYkc5FtP.......................EXFHm37aDvcMtCvnYfmvQ"
    }
  },
  "credentialStatus": {
    "claim": {
      "id": "vc:hid:testnet:................",
      "currentStatus": "vc:hid:testnet:................",
      "statusReason": "Credential is active"
    },
    "issuer": "did:hid:testnet:..............",
    "issuanceDate": "2023-01-25T16:59:21Z",
    "expirationDate": "2023-01-25T16:59:21Z",
    "credentialHash": "ae93886f2a............3f6d1c6ae4..........393d43730",
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2023-01-25T17:01:02Z",
      "verificationMethod": "did:hid:testnet:...............#key-${id}",
      "proofPurpose": "assertionMethod",
      "proofValue": "z5LairjrBYkc5FtP.......................EXFHm37aDvcMtCvnYfmvQ",
      "updated": "2023-01-25T17:01:02Z"
    }
  },
  "persist": true,
  "retrieveCredential": true
}