Setup a Credential Offer

Introduction

To kick off the credential issuance flow, you need to make a Credential Offer available to the Mobile Wallet App.

This guide will step through how that can be achieved by setting up the offer and then hosting the URL reference in a QR code.

Pre-Requisites

You need access to the MATTR Platform APIs. If you're experiencing difficulty, contact us

The Credential Offer

The Credential Offer is designed to contain enough information for a client (Mobile Wallet App) to ingest and present a screen to the user to establish consent before kicking off an OpenID Connect based Credential flow via an Authorization Request.

Create an Offer

Create an Offer by providing a payload:

POST https://tenant.platform.mattr.global/v1/credentials/offers

Request

{
"issuerDid": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
"issuerDescription": "My Issuer",
"provider": "35b518a0-a557-11ea-8f33-67952e8f07c3",
"credentialDescription": "My Custom Credential",
"claims": {
"credential": {
"http://schema.org/givenName": {
"essential": true
},
"http://schema.org/familyName": {
"essential": true
},
"http://schema.org/educationalCredentialAwarded": {
"essential": true
}
}
}
}

Display Values

The values of issuerDescription and credentialDescription will appear in the mobile Wallet App, so they should be meaningful for the user.

The Credential Layout

In order to provide the correct claims for a Credential issued in JSON-LD format, the Offer requires claims with fully-qualified-names (FQN) JSON-LD term to an existing data schema.

At present the platform only supports schema.org data schema for its data vocabularies. If you need further vocabularies then please let us know to take into consideration for the future roadmap.

Note: the final pathname of claims.credential will be visible on the mobile Wallet App.

Response

{
"domain": "tenant.platform.mattr.global",
"offerId": "004a6350-99ef-11ea-a609-ef8f3a51399f",
"purpose": "credential_offer",
"issuerDid": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
"issuerDescription": "My Issuer",
"provider": "35b518a0-a557-11ea-8f33-67952e8f07c3",
"credentialDescription": "My Custom Credential",
"claims": {
"credential": {
"http://schema.org/givenName": {
"essential": true
},
"http://schema.org/familyName": {
"essential": true
},
"http://schema.org/educationalCredentialAwarded": {
"essential": true
}
}
}
}

Embed the Offer ID

The Offer can be resolved publicly from your tenant by the offerId

GET https://tenant.platform.mattr.global/v1/credentials/offers/004a6350-99ef-11ea-a609-ef8f3a51399f

The Authorization header is not required as it is intended for a Mobile Wallet client to resolve.

Resolving a URL

When installed, the Mobile Wallet registers a protocol handler didcomm://

The request URL can be wrapped in this protocol and opened on a mobile device with the MATTR Wallet App installed.

didcomm://https://tenant.platform.mattr.global/v1/credentials/offers/004a6350-99ef-11ea-a609-ef8f3a51399f

Standards in this area are still being normalized, a user may find they already have installed another app that has registered this protocol. They will still be able to read the QR code after opening the MATTR Wallet App

Embed in a QR Code

A common way to serve the Offer is to embed the didcomm://request into a QR.

Remember the Offer is long-lived and can be referenced by many clients. You could even print out the QR code.

There are many QR generation services available:

MATTR is not affiliated with any of these service providers and cannot voucher for their offerings.

Make sure to make the QR a decent size to be resolvable by a phone camera, 200px square is a fine.

Let's use an API service to generate the QR code.

https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=didcomm://https://tenant.platform.mattr.global/v1/credentials/offers/004a6350-99ef-11ea-a609-ef8f3a51399f

Try it out

By now you should just be able to open the MATTR Wallet app, go to 'scan' and then point the camera at the QR code.

You should see the Credential Offer displayed for you to Accept or Decline.

You can also try to open the didcomm:// link directly on the phone (hint: send it via a message or email).

Some phones (most iPhones and Samsungs) have built in handlers for reading QR codes, try just pointing the regular camera app at the QR code to see if it works!

Troubleshooting

Due to the nature of differing mobile devices linking together, you may encounter some technical difficulties while running this tutorial. Below are a few common problems and their solutions.

The App opens but refuses to show an Offer

  • Check that you have encoded the OfferId correctly in the QR
  • Your phone will need public internet access, check it can access common websites
  • Check that you can open the exact URL embedded in the code
  • Make sure you have the MATTR Mobile Wallet app setup with a PIN

The MATTR Mobile Wallet app registers the didcomm:// protocol on setup

Scanning the QR code using the phone's camera doesn't open the app (opens Google search or tries to load in the browser and fails)

  • Make sure you have the MATTR Mobile Wallet app setup with a PIN
  • Make sure the QR is large enough to be read by your phone; try creating a larger QR Code, say 300 x 300 px