Distribute a verifiable document via a QR code (URL)
Using a QR code is one of the recommended Universal Actions through which OpenAttestation documents can be distributed or communicated. The purpose of Universal Actions is to implement a standard for all parties to share OpenAttestation documents.
The QR code used in the OpenAttestation framework is essentially a URL where you can embed an OA document to make it easily shareable. In this way, the verifying party only needs to scan the QR code to view the verifiable document.
Example QR code and link
The following shows an example QR code:
The following shows the link in the QR code above:
Generating your shareable URL
The shareable URL contains the URL to the compatible verifier, along with a query parameter (q) containing an encoded payload, and a hash (#) followed by the optional decryption key.
The syntax of the shareable URL is in the following:
https://[VERIFIER_URL]/?q=[ENCODED_QUERY_PARAM]#[OPTIONAL_DECRYPTION_KEY]
In the URL, the query parameter (q) consists of an encoded query string of a JSON. If you analyze the URL in your preferred URL decoder, you will see the query parameter (q) decoded to a JSON string similar to the following example:
{
"type": "DOCUMENT",
"payload": {
"uri": "https://gallery.openattestation.com/static/documents/transcript-encrypted.opencert",
"permittedActions": [
"STORE"
],
"redirect": "https://dev.opencerts.io"
}
}
For the ease of reading, here’s how an unencoded URL looks like:
Note: The bold portion has to be encoded separately.
Mandatory information in the QR code
The table below describes the JSON key/value pairs for the query parameter q for the verifier to handle:
Query Parameter q | ||||
| Key | Necessity | Definition | Data Type | Value |
type | Required | Data type of the information that the QR code presents. | Enum | The following value option is accepted:
|
payload | Required | An object that consists of three variables, including uri, permittedActions, and redirect. | Object | The three variables in this object must follow the respective requirements on their value options. |
payload.uri | Required | A URI where the verifiable document is hosted. | URI | A valid URI pointing to the document that is retrievable by the verifier.
Example: S3 Bucket |
Optional information in the QR code
The table below describes the JSON key/value pairs for the optional URI fragment (hash #):
Hash # | ||||
| Key | Necessity | Definition | Data Type | Value |
key | Optional | Decryption key hexadecimal encoded | String | Any key compliant with OpenAttestation encryption is accepted. |
payload.permittedActions | Optional | The actions that the user will be able to perform on the document. | Enum | The following value options are accepted:
|
payload.redirect | Optional | A URI where the OA-compliant verifier resides. | URI | A valid URI pointing to any compatible verifier is accepted. |
Embedding a document in a QR code
To share an OA document via a QR code:
-
Collect all mandatory information that the QR code requires.
- To prevent any possible security breach, you have the option to encrypt confidential information and add a decryption key into the QR code.
- To learn more about OpenAttestation encryption, see this GitHub repository.
-
Place the mandatory fields into their respective JSON key/value pair.
-
Use your preferred URL encoder to encode the query parameter (q) and hash (#) so that it can be inserted into the URL.
-
Use your preferred QR code generator to turn the URL into a QR code.
-
Share the QR code with other users, so that they can view the document in a compatible verifier.
Additional information about the distribution methods
To learn more about the pros and cons of QR code and other distribution methods, see this article.