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

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

schemaIdstringOptional

schemaId for credential Schema

subjectDidstringRequired

holder did of the credential

issuerDidstringRequired

issuerDid of the credential

expirationDatestringRequired

Date in ISOString format

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

fieldsobjectRequired

Credential Data fields

Example: {"name":"Random name"}

namespacestringRequired

Namespace to be added in vcId.

Example: testnet

verificationMethodIdstringRequired

Verification Method id for did updation

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

persistbooleanRequired

Persist in edv

Example: true

Responses

201

Credential Created

application/json

400

Error occured at the time of creating credential

application/json

404

Resource not found

application/json

post

/api/v1/credential/issue

HTTPcURLJavaScriptPython

POST /api/v1/credential/issue HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 234

{
  "schemaId": "text",
  "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"
}

{
  "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

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

Responses

200

verification result of credential

application/json

verifiedbooleanRequired

result of credential verification

400

Error occured at the time of verifying credential

application/json

404

Resource not found

application/json

post

/api/v1/credential/verify

HTTPcURLJavaScriptPython

POST /api/v1/credential/verify HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1018

{
  "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"
    }
  }
}

{
  "verified": true,
  "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

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

credentialIdstringRequired

Query parameters

retrieveCredentialbooleanOptional

Header parameters

AuthorizationstringOptional

Bearer <access_token>

OriginstringOptional

Origin as you set in application cors

Responses

200

Resolved credential detail

application/json

persistbooleanRequired

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

Example: true

retrieveCredentialbooleanRequired

If set true then return credential Document also

Example: true

404

Credential with id vc:hid:testnet:...... not found

application/json

get

/api/v1/credential/{credentialId}

HTTPcURLJavaScriptPython

GET /api/v1/credential/{credentialId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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

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

List of credentials

application/json

totalCountnumberRequired

totalCount

Example: 12

dataobject[]Required

data

Example: ["vc:hid:testnet:............"]

404

Error in finding resource

application/json

get

/api/v1/credential

HTTPcURLJavaScriptPython

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

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

Update credential status of a verifiable credential

patch

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

credentialIdstringRequired

Header parameters

AuthorizationstringOptional

Bearer <access_token>

OriginstringOptional

Origin as you set in application cors

Body

application/json

namespacestringRequired

Namespace to be added in vcId.

Example: testnet

statusstringRequired

Credential status

Example: LIVE / SUSPEND / REVOKE

statusReasonstringRequired

Credential status Reason

Example: Reason

issuerDidstringRequired

issuerDid of the credential

verificationMethodIdstringRequired

Verification Method id for did updation

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

Responses

200

Credential Updated

application/json

persistbooleanRequired

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

Example: true

retrieveCredentialbooleanRequired

If set true then return credential Document also

Example: true

400

Error occured at the time of creating credential

application/json

404

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

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /api/v1/credential/status/{credentialId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 162

{
  "namespace": "testnet",
  "status": "LIVE / SUSPEND / REVOKE",
  "statusReason": "Reason",
  "issuerDid": "text",
  "verificationMethodId": "did:hid:testnet:........#key-${idx}"
}

{
  "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
}