// Developer Guide – april 2023 – by nubis //

From ∅ ↦ issuing diplomas.

certificates of attendance & badges too.

You can use CONSTATA to issue certified documents in verifiable HTML format, digitally signed by you, and timestamped in the Bitcoin blockchain.

A verifiable html document is a diploma, certificate of attendance or badge, that can be shared online or downloaded and stored. It can be viewed and verified by anyone, using only their default web browser — forever.

These documents are generated from a template. This guide will show you how to issue a batch of diplomas from the default template, interacting with our GraphQL API from the command line.

You should eventually hire us to make you a template with a custom look that can also include extra information such as a student photo, grades and transcripts.

Who's this guide for? How is it used?

This guide is for sysadmins writing shell scripts that use Constata, and technical people looking into the issuances API capabilities.

It's meant to be followed step by step in BASH for Linux, but should work on Windows and Mac with minimal changes.

If you need help, find an error, or juts find it confusing, email us at devops@constata.eu.

Are you a developer integrating our API? After reading this, check out our GraphQL API explorer and github repo — specially the rust client library which powers the command line tool, and the C# client library.

Non technical? No worries, we have a WEB3 app to do this right from your browser, just go here.


  1. Generate your digital signature.
  2. Get the command line utility.
  3. List the students in a CSV file.
  4. Submit your CSV to create an Issuance.
  5. Sign the diplomas.
  6. Relax while we do our magic.

Generate your digital signature.

You can do this by signing up for constata. It's quick, and providing your email address is optional — we only require it if you want to us to send diplomas via email.

The signup process will create a password protected private key in your device, and will offer to save a signature.json file which you will use to authenticate in the command line utility.

Constata never knows your private key, you should contact us if you think it has been compromised.

Each request to our website and API is signed on your device following the Bitcoin sign message protocol, using the generated key.

You can also signup on our staging environment, which mimics the production service. Email us to request unlimited credit for issuing diplomas on staging.

Documents generated on staging are for testing purposes only, they are not covered by our terms and conditions, and will be timestamped on the insecure bitcoin testnet network.

Get the command line utility.

$ wget -q https://github.com/constata-eu/constata/releases/download/latest/constata-cli-linux $ chmod +x constata-cli-linux $ ./constata-cli-linux help help Print this message or the help of the given subcommand(s) Usage: constata-cli-linux help [COMMAND]... Arguments: [COMMAND]... Print help for the subcommand(s)

The Constata API is built on GraphQL and requires signing each request for authentication, so we built this utility to perform authenticated requests and parse the results from the command line.

These are the download links to the precompiled binaries for Linux, Windows and Mac OS. They're always available with release notes in the latest release page

We statically link the binaries for your convenience, but our code is open source, you can fork the client and build your own.

List the students in a CSV file.

$ cat <<EOF > students.csv name;email;custom_text;motive;date;place Alice Doe;alice@example.com;Blockchain Expert;XXI Blockchain Masterclass;May 30, 2023;The Metaverse Bob Bobson;bob@example.com;Blockchain Expert;XXI Blockchain Masterclass;May 30, 2023;The Metaverse EOF

If you verify your email address with constata you'll gain access to our emailing features — then you can change Alice's email and have the diploma delivered there.

You can use either , [colon] or ; [semi-colon] as column separators. The maximum size allowed for a CSV file is 50 megabytes.

This CSV has columns that are compatible with the default template, we call this column definition a schema.

When you hire us to make your custom template we will give you an example CSV file to go with its schema.

You can also query your existing templates to see their schemas and which fields are required.

$ ./constata-cli-linux all-templates

Submit your CSV to create an Issuance.

$ ./constata-cli-linux create-issuance-from-csv "Test issuance name" --csv-file=students.csv \ --new-kind=diploma --new-name="My Template" --new-logo-text="Widgets Inc." { "id": 265, "templateId": 164, "templateName": "My Template", "templateKind": "DIPLOMA", "state": "received", "name": "Test issuance name", "createdAt": "2023-04-20T19:27:01.355285Z", "errors": null, "tokensNeeded": null, "entriesCount": 2, "adminVisitedCount": 0, "publicVisitCount": 0 }

This command will produce a new Issuance with 2 Entries — one for each student — but the actual diplomas are rendered asynchronously, this means your issuance starts out in a state of received, and will transition to created after a few seconds.

You can wait until this issuance, with id 265, is created to make sure we're ready to review and sign.

$ ./constata-cli-linux issuance-state 265 created --wait

We're also creating a clone of our default template in the same command with the --new-kind, --new-name and --new-logo-text options. See the command's help for more options.

$ ./constata-cli-linux help create-issuance-from-csv

The only customization allowed for the default template is adding either your company name or company logo image. We suggest you hire us to make you a custom template if that's not enough.

Or submit each entry using JSON.

$ ./constata-cli-linux --json-pointer=/id create-issuance-from-json "Another Test" --template-id 164 266 $ ./constata-cli-linux append-entries-to-issuance 266 --entry='{"name":"Bob","motive":"Accredited Expert"}' { "id": 266, "templateId": 164, "templateName": "My Template", "templateKind": "DIPLOMA", "state": "received", "name": "Another Test", "createdAt": "2023-04-20T19:27:01.355285Z", "errors": null, "tokensNeeded": null, "entriesCount": 1, "adminVisitedCount": 0, "publicVisitCount": 0 }

The example above starts a new Issuance with no entries. It also uses the --json-pointer argument to only output the new issuance's id instead of the full JSON. The second command adds a single Entry as JSON.

There are many options and variations to both commands, such as sending several entries at once, or using a JSON file. Each command's help will tell you more.

Entries can be added freely up until you start sigining. No new entries are allowed after that point.

Sign the diplomas.

$ ./constata-cli-linux preview-sample-from-issuance 265 preview.html && open preview.html Preview for entry 265 saved to file Opening in browser window $ ./constata-cli-linux sign-issuance 265 Signing entry 1 of 2 Signing entry 2 of 2

That last command downloads and signs each entry, moving the issuance from state createad to state signed. It may take some time to sign all entries, but the process can be safely interrupted and resumed.

It's generally a good idea to read before you sign — so the first command grabs a preview from one of the issuance entries and opens it up in your browser.

You can also list all the issuance entries and preview specific ones with these two commands below.

$ ./constata-cli-linux all-entries --issuance-id-eq=265 $ ./constata-cli-linux preview-entry <entry_id> preview.html

Some charges apply.

$ ./constata-cli-linux --json-pointer=/missing account-state 2 $ ./constata-cli-linux --json-pointer=/pendingInvoiceLinkUrl account-state https://api.constata.eu/#/invoice/note+computer+beach+music+train

You pay for your issuance right after signing it, using constata tokens — do check your account-state to make sure you are not missing any.

If you are missing tokens your entries may be put on hold and we will contact you, but you can also buy them visiting pendingInvoiceLinkUrl.

Premium customers may have credit up to an agreed amount, or a flat fee, and never run out of tokens.

For the purposes of this guide we will assume you're recently signed up to the free tier, which gives away up to 10 tokens a month for issuing diplomas.

For staging, you must contact us to give you unlimited credit.

Relax while we do our magic.

$ ./constata-cli-linux --json-pointer=/allIssuances/0/state all-issuances --id-eq 265 "completed" $ if ./constata-cli-linux issuance-state 265 completed; then ./constata-cli-linux issuance-export 265 issuance_exported.csv fi Export for Issuance #265 saved to file

We will process your signed issuance and move it to state completed, this usually takes less than one hour. You should poll every couple of minutes to check if its ready as shown in the example above.

If you are ok with a long running process, this variant will block until the issuance is completed.

$ ./constata-cli-linux issuance-state 265 completed --wait

The certification process may take longer due to blockchain network conditions out of our control, but we're always monitoring and actively accelerating the process.

Each entry will have a special administrative access url you can share with the students, where they can view or download their diploma, as well as share it online and manage their data protection rights.

This link is emailed to them immediately if you provide their email address — remember to verify your own email to enable this feature.

You can also export your issuance back to CSV, the exported CSV will include the original columns and will maintain their ordering, but it will also have new columns like the constata_admin_access_url. You could feed it to mass mailing tools like mailchimp or sendinblue if you rather manage your own mailing.

Query your issuance and its entries like this.

$ ./constata-cli-linux --json-pointer=/allIssuances/0 all-issuances --id-eq=265 $ ./constata-cli-linux all-entries --issuance-id-eq=265

That's it!

You've just issued your first verifiable diplomas with Constata.

For brevity — which by now you now I struggled to achieve — most of the options on the command line utility were left out, I suggest you check the subcommands help.

If you have any comments you can reach out to us via email, github, or on our other social networks, find the links in the footer.

This guide itself is available in our github repo and pull requests are welcome.