ShoCard
Last updated July 28, 2023
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
The ShoCard add-on is currently in beta.
Table of Contents
ShoCard is an add-on for mobile user identity which allows secured login and registration on your website.
ShoCard is accessible via an API and has a reference client demo application implementation in Ruby.
Provisioning the add-on
ShoCard can be attached to a Heroku application via the CLI:
A list of all plans available can be found here.
$ heroku addons:create shocard
-----> Adding shocard to sharp-mountain-4005... done, v18 (free)
Once ShoCard has been added the following settings will be available:
-
SHOCARD_IDis your unique identifier on the blockchain (automatically set) -
SHOCARD_CERTIFIER_IDis the certification server identifier (automatically set) -
SHOCARD_ADAPTOR_URLis a URL of the security adaptor (automatically set) -
SHOCARD_QR_URLis a URL of the ShoStore server (automatically set)
Those can be confirmed using the heroku config:get command.
$ heroku config:get SHOCARD_ID
12inxZNnurJ6A5vYqMxVCktj6tiQqt9zG4
Development portal integration
After adding the ShoCard add-on to your application we will automatically provision your user and application in our development portal. You can access it by clicking on the ShoCard add-on in the Heroku Dashboard.
You have to setup the callback parameter in the developer portal. Please follow the instructions on the portal page.
Application integrations
ShoCard server will communicate with your application via a JSON REST API which you need to implement.
Here’s a list of APIs to be implemented:
Registration: PUT /sessions/:ssid/certify
ShoCard will call this endpoint whenever a mobile client attempts a register (by scanning a QR code on your website).
Parameters in the request are:
- approval - true if user accepted a registration request
- shocardid - shocardid of the mobile client
- ssid - a secret, should match the secret put in the QR code
Login: PUT /sessions/:ssid/login
ShoCard will call this endpoint whenever a mobile client attempts to login (by scanning a QR code on your website)
Parameters in the request are:
- approval - true if user accepted a login request
- shocardid - shocardid of the mobile client
- ssid - a secret, should match the secret put in the QR code
Dashboard
For more information on the features available within the ShoCard dashboard please see the docs at https://shocard.io.
The ShoCard dashboard allows you to change application name and set a callback.
The dashboard can be accessed via the CLI:
$ heroku addons:open shocard
Opening ShoCard for sharp-mountain-4005
or by visiting the Heroku Dashboard and selecting the application in question. Select ShoCard from the Add-ons menu.
Migrating between plans
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
Use the heroku addons:upgrade command to migrate to a new plan.
$ heroku addons:upgrade shocard:newplan
-----> Upgrading shocard:newplan to sharp-mountain-4005... done, v18 ($49/mo)
Your plan has been updated to: shocard:newplan
Removing the add-on
ShoCard can be removed via the CLI.
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy shocard
-----> Removing shocard from sharp-mountain-4005... done, v20 (free)
Note that while removing the ShoCard add-on, the actions (seals and certifies) of the applications will still persist on the blockchain and on the ShoCard servers due to the nature of blockchain being a public irreversible ledger. Under no circumstances ShoCard persists personal user information in the seal data, only hashes/signatures used for data integrity verification.
Support
All ShoCard support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@shocard.com.