Creating an encrypted Status List 2021 Resource using Credential Service
To create an encrypted Verifiable Credential Status List v2021 with a set of Access Control Conditions, an Issuer will need to follow the steps below:
Make sure you have set up your account with Credential Service and are logged in, using our guide below:
Before you can create an encrypted Status List for charging for Credentials, you need to create a DID which is used to link the Status List on-ledger. Use the API in the page below to create a DID:
When creating a Status List, a user will have the following options:
For the purpose of this tutorial, we will assume the user is creating an encrypted Status List. For unencrypted Status Lists, follow the tutorial here.
Using the /credential-status/create/encrypted
API, users have two options for creating an encrypted Status List on-ledger:
Filling out a simple form using the application/x-www-url-form-encoded
option on the Swagger UI.
Compiling a Status List payload yourself using the application/json
option on the Swagger UI.
This is the easiest way to create encrypted Status Lists on cheqd and is recommended for users who are not overly familiar with compiling JSON objects.
Using the application/x-www-url-form-encoded
option on the Swagger UI, users are able to choose between the following variables and options to create an encrypted Status List on-ledger:
From this request, the Credential Service will automatically create and publish an encrypted Status List to the ledger with set Payment Conditions required to be met to unlock.
Instead of using simple form variables, you can create an encrypted Status List using a JSON payload yourself using the application/json
option on the Swagger UI.
An example of the JSON payload needed to be submitted is below:
The table below expands on some of the required parameters:
Once the Issuer has populated the requisite information for the encrypted Status List request, they can use the API below to submit it to the ledger.
The following code snippet shows an example of an encrypted Status List response format, which will be published to the ledger:
Note: it is important to save the response, including the "encryptedSymmetricKey
" locally, as this will be used for updating encrypted Status List operations.
Note: The only encrypted element is the "encodedList
" element. This provides the Verifier sufficient information to be able to make the payment back the the Issuer and to fulfill the Access Control Conditions, without being able to see the contents of the Status List itself.
How a Verifier pays an Issuer to decrypt an encrypted Status List
Credential Service supports payments for verifying Credential Status. This is an innovative feature that is also commonly known as cheqd's Payment Rails. Using the API in this tutorial, there are multiple ways for a Verifier to pay an Issuer to unlock and verify a Credential's status.
A Verifier will need a Credential Service account to take advantage of the /credential-status/check
API and easily use cheqd's Credential Payments. Make sure you are set up and are logged in, using our guide below:
Using the /credential-status/check
API, users have two options for checking whether a particular Credential index is revoked or suspended:
Filling out a simple form using the application/x-www-url-form-encoded
option on the Swagger UI.
Compiling the JSON transaction yourself using the application/json
option on the Swagger UI.
This is the easiest way to check whether a particular credential index is revoked or suspended.
Using the application/x-www-url-form-encoded
option on the Swagger UI, users are able to choose between the following variables to compile your DID:
To automatically make a payment to an Issuer in order to verify an encrypted Status List, there is an additional variable:
If there is sufficient CHEQ in the account of the Verifier, this will automatically make a payment to the Issuer and meet the Access Control Conditions.
In the same action, the Credential Service will perform a verification check on the Credential Status and pay the issuer the fee specified in the Payment Conditions.
The response format below will indicate clearly whether the check is successful and whether the Credential index in question is revoked / suspended or not.
If a Verifier does not want to automatically pay the Issuer using the API, they can choose to make a manual payment to unlock the Credential Status information to build a higher level of trust within the Credential presented to them.
If a Verifier wants to unlock access to the Resource, to gain access to additional information about a Credential presented to them, such as the Credential Status, firstly, the Verifier will be presented Credential, including a link to the Status List within the "credentialStatus"
section of the Credential body.
Through following the link in"credentialStatus"
section of the Credential body. the The Verifier will be directed to an on-ledger Resource, identifiable through a DID URL, for example:
This on-ledger Resource will contain:
An encrypted potion of the Resource, such as a Status List bitstring. identified by the "encodedList"
property.
Unencrypted metadata about the Resource, including the issuers' payment address "feePayerAddress"
and and the Payment Conditions, "feePaymentAmount"
and "intervalInSeconds"
.
This gives the verifier requisite information they need in order to pay the Issuer to unlock the Credential Status. You can learn more about Access Control Conditions below.
This payment should be made in CHEQ.
Note that the "feePaymentAmount"
may be specified in ncheq. This is lowest denomination of the CHEQ token, "nano" CHEQ which is 1 x 10^-9 CHEQ.
The Credential Service will perform a verification check on the Credential Status and pay the issuer the fee specified in the Payment Conditions.
Note the "intervalInSeconds
" which is the amount of time after making the payment that the Verifier has to hit the API and request access to the encrypted Status List.
The response format below will indicate clearly whether the check is successful and whether the Credential index in question is revoked / suspended or not.
Alternatively, if Verifiers have made the payment manually they can also use the /credential/verify API in the tutorial below:
Parameter | Example value | Description |
---|---|---|
Using one of , Verifiers can make a payment of the amount specified in the "feePaymentAmount"
to the "feePayerAddress"
.
"feePaymentAddress"
"cheqd1xl5wccz667lk06ahama26pdqvrkz5aws6m0ztp"
This specifies the cheqd address to which the payment fee should be sent. This address is associated with the User who wants to charge for Credential Status
"feePaymentAmount"
"1000"
This defines the amount of the payment fee in CHEQ which the Issuer will charge for a third party to unlock the Credential Status.
The amount may be up to 2 decimal points, e.g. "1000.25
".
"feePaymentWindow"
"10
"
The amount of time, in minutes, after making the payment in which a Verifier is able to unlock an encrypted resource.
Set up your account
Set up your account with cheqd Credential Service and log in to start using the APIs.
Create an Issuer DID
Create a W3C conformant DID on cheqd using the did:cheqd
DID Method.
Verify Credential
Verify a W3C Verifiable Credential using cheqd's Credential Service APIs.
The /credential-status/update/encrypted
API enables users to update the indices of a Status List or rotate the encryption keys. This may be useful for revoking Credentials in bulk, rather than submitting individual /credential/revoke
requests.
When a new encrypted Status List resource is published, this will also encrypt the latest version with a new set of encryption keys. This may therefore be used to rotate encryption keys, even if the listed indices are kept the same.
Credential Payments brings a significant evolution to the Verifiable Credentials landscape, allowing verifiers to directly pay issuers to unlock Credential Status information. Underneath the hood, we've engineered a robust and secure payment flow that streamlines the end-to-end payment process, with accuracy, speed, and cryptographic integrity.
Create encrypted Status Lists on-ledger, and pay to unlock the Access Control Conditions in CHEQ, using our Credential Payments APIs:
Build your understanding of How Credential Payments work, including Access Control Conditions and how the model preserves privacy.
Below are a list of alternatives for using Credential Payments.
Understand how to issue a Verifiable Credential including an encrypted Status List in the body.
Issuers are able to add encrypted Status Lists to the body of the Credential if they have previously created an Encrypted Status List on-ledger.
Make sure you have set up your account with Credential Service and are logged in, using our guide below:
Before you can create an encrypted Status List for charging for Credentials, you need to create a DID which is used to link the Status List on-ledger. Use the API in the page below to create a DID:
Follow the tutorial here to create an encrypted Status List with a set of Payment Conditions to unlock:
Follow the instructions within the /credential/create
API below to format and issue a Verifiable Credential.
Ensure that the "statusListName
" and "statusPurpose
" are the same as the Status List created in Step 3. This makes sure that if the Credential Status is changed, for example, if it is revoked or suspended, the correct Status List will be updated.
Charge for Status List
With Credential Payments, Issuers are able to create payment-gated Status Lists in order to charge for the verification of Credential Status information.
Issue Credential with Encrypted Status List
Issue a Verifiable Credential referencing an encrypted Status List in the body, with a specified bitstring index.
Verifier pays Issuer
Understand how a Verifier pays an Issuer in CHEQ to unlock Status List and verify Credential Status.
Bulk Update or Rotate Encryption Keys
Update a set of Credential indices or rotate the encrypted symmetric key for the Status List.
Understanding Credential Payments
Before diving into Credential Payments, developers may want to learn how the Payment gating and Access Control condition logic works.
Why are we payment gating Status Lists?
Learn about the role of cheqd in Trusted Data Markets and why we are payment gating the "reputability" of Credentials.
Veramo SDK Plugin
The Veramo SDK Plugin is an extension of the Veramo SDK, a JavaScript framework for Trusted Data, adding support for cheqd functionality.
Set up your account
Set up your account with cheqd Credential Service and log in to start using the APIs.
Create an Issuer DID
Create a W3C conformant DID on cheqd using the did:cheqd
DID Method.
Charge for Status List
Create an encrypted Status List on-ledger with Payment Conditions to unlock, to charge for unlocking Status Lists.
Issue Credential
Issue a W3C conformant Verifiable Credential using the Credential Service APIs.