Create a Web Credential
Prerequisites
Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.
DIDs:
Issuer DID: This is a
did:web
that identifies the issuer who attests the claims in the credential are accurate. Refer to create a did:web if you need assistance in creating one. You can only sign Web Credentials using DIDs with aed25519
orbls12381g2
key type. Note that MATTR VII createsdid:web
s with both of these key types by default.Subject DID: This is a
did:key
that identifies the intended holder of the credential. This DID is usually retrieved from the intended holder's digital wallet. Refer to create a did:key if you need assistance in creating one for testing this feature. In production environments you must have a secure way to obtain it:Use DID Auth for any new interactions.
Ask the user to share their wallet DID (MATTR Showcase wallet or MATTR GO users can do this by navigating to Settings > Advanced > Public DID).
Request an existing credential as part of a verification workflow, and extract the DID from that interaction.
Credential structure:
Credential type.
JSON-LD claim names as defined by schema.org.
Claim values: The claims you wish to include in the credential. This is the information attested by the issuer.
Request
Make the following request to create and sign a new Web Credential:
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/sign
1{
2 "payload": {
3 "name": "Course credential",
4 "description": "Diploma in Management",
5 "type": [
6 "EducationalOccupationalCredential",
7 "AlumniCredential"
8 ],
9 "credentialSubject": {
10 "id": "did:key:z6Mkr9f7o82NFLRFTTCWRR1GiZpca22Xf6YKo2zKThrZMA2w",
11 "givenName": "Emma",
12 "familyName": "Tasma",
13 "alumniOf": "Zealopia University"
14 },
15 "credentialBranding": {
16 "backgroundColor": "#860012",
17 "watermarkImageUrl": "https://static.mattr.global/credential-assets/zealopia/web/watermark.svg"
18 },
19 "issuer": {
20 "id": "did:web:learn.vii.au01.mattr.global",
21 "name": "Zealopia Business Institute",
22 "iconUrl": "https://static.mattr.global/credential-assets/zealopia/web/logo.svg",
23 "logoUrl": "https://static.mattr.global/credential-assets/zealopia/web/icon.svg"
24 },
25 "expirationDate": "2024-02-01T08:12:38.156Z",
26 "issuanceDate": "2023-02-01T08:12:38.156Z"
27 },
28 "proofType":"Ed25519Signature2018",
29 "tag": "external-identifier",
30 "persist": false,
31 "revocable": true
32}
name
: Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder's digital wallet (see image below). Maximum length is 18 characters. Additional characters will not be displayed.description
: Insert a meaningful description for the credential. This string is displayed below thename
field on the credential in the holder's digital wallet (see image below). Maximum length is 38 characters. Additional characters will not be displayed.type
: This array of credential types indicates what sort of information a credential holds. This is a unique identifier used to differentiate between various Web Credential types. MATTR VII automatically injectsVerifiableCredential
as the first value of this array, and you must include at least one additional value in the request payload.credentialSubject
:id
: Insert the DID that identifies the intended holder and is associated with their digital wallet. This is what binds this credential to a specific holder.givenName
: Example for a custom claim.familyName
: Example for a custom claim.educationalCredentialAwarded
: Example for a custom claim.
credentialBranding
:backgroundColor
: Insert a colour hex code to use for the credential background color in the holder's digital wallet (see image below). Refer to this video to learn more about branding best practices.watermarkImageUrl
: Insert a URL for a watermark image to be included as a pattern on the credential in the holder's digital wallet (see image below):Must be publicly available.
Must be 245x150 px in size.
svg, png and jpg files are supported, but svg is recommended.
Refer to this video to learn more about branding best practices.
issuer
:id
: Use the DID that identifies the credential's issuer, which attests the claims in the credential. This must be a publicly available and resolvabledid:web
for the credential to be valid and verifiable.name
: Insert a meaningful name to indicate the issuer. This string is used when the credential is offered to the holder. It is also used on the bottom part of the credential whenlogoURL
is not provided.logoUrl
: Insert a URL for a logo that is displayed on the bottom part of the credential (see image below). If no logo is provided, the issuer'sname
andIconUrl
are used instead. The logo must meet the following criteria:URL must be publicly available.
Must be 140x42 px in size.
svg, png and jpg files are supported, but svg is recommended. Raster images, whilst supported, are currently displayed at 1x resolution and may look pixelated on some devices.
Transparencies are allowed for svg or png images.
If no logo is provided, the first letter of the issuer name is displayed instead.
Refer to this video to learn more about branding best practices.
iconUrl
: Insert a URL for an icon that is displayed next to the issuer's name when the credential is offered to the holder. It is also displayed next to the issuer's name on the bottom part of the credential whenlogoURL
is not provided. WheniconURL
is not provided, the first letter from name is used instead. The icon must meet the following criteria:URL must be publicly available.
Must be 32x32 px in size.
svg, png and jpg files are supported, but svg is recommended. Raster images, whilst supported, are currently displayed at 1x resolution and may look pixelated on some devices.
Transparencies are allowed for svg or png images.
Refer to this video to learn more about branding best practices.
expirationDate
: Insert the credential expiration date, after which it will not be considered valid and cannot be verified. Expiration date can not be in the past.issuanceDate
: This is an optional field that enables defining when the credential becomes valid. This can be used to issue future-dated credentials. Value must not be in the past or afterexpirationDate
, when the latter is specified. When not specified,issuanceDate
will default to the current time.proofType
: This is an optional field which defines the cryptographic algorithm used to sign the credential. The credential Issuer's DID must contain a key that supports the corresponding signing capability. If noproofType
is provided, the credential will be signed using the key that is available in the Issuer's DID:If a
Bls12381G2
key is available, the credential will be signed with aBbsSignature2022
proof. Credentials signed with this proof type support selective disclosure.If a
Bls12381G2
key is unavailable, but aEd25519
key is available, the credential will be signed with aEd25519Signature2018
proof. Credentials signed with this proof type do not support selective disclosure.If none of the two suitable keys are available, the request will be rejected and the credential will not be created.
tag
: Insert a tag to reference this credential. The gets stored as part of the credential metadata and can be used to search for it in the credential registry. Note that tags are case sensitive.persist
: When set totrue
, both the credential and the credential metadata are stored in the credential registry. When set tofalse
, only the following metadata is stored in the credential registry:id
tag
credentialStatus
issuanceDate
Credentials by nature tend to hold Personally Identifying Information (PII). Before storing credential data, familiarise yourself with compliance to any PII restrictions that may apply to your use-case.
revocable
: When set totrue
, the created credential can later be revoked. When set tofalse
, the credential cannot be revoked. When set totrue
,https://w3id.org/vc-revocation-list-2020/v1
is injected into the credential@context
object when it is issued. This references the JSON-LD definition of thecredentialStatus
object.
Response
1{
2 "id": "b955f2f1-2ea7-4225-a74e-4111094074be",
3 "tag": "external-identifier",
4 "credential": {
5 "type": [
6 "VerifiableCredential",
7 "EducationalOccupationalCredential",
8 "AlumniCredential"
9 ],
10 "issuer": {
11 "id": "did:web:learn.vii.au01.mattr.global",
12 "name": "Zealopia Business Institute",
13 "logoUrl": "https://static.mattr.global/credential-assets/zealopia/web/icon.svg",
14 "iconUrl": "https://static.mattr.global/credential-assets/zealopia/web/logo.svg"
15 },
16 "name": "Course credential",
17 "description": "This credential shows that the person has attended the mention course and attained the relevant awards.",
18 "credentialBranding": {
19 "backgroundColor": "#6303FF",
20 "watermarkImageUrl": "https://static.mattr.global/credential-assets/zealopia/web/watermark.svg"
21 },
22 "issuanceDate": "2024-01-10T22:54:57.083Z",
23 "expirationDate": "2025-02-01T08:12:38.156Z",
24 "credentialSubject": {
25 "id": "did:key:z6Mkr9f7o82NFLRFTTCWRR1GiZpca22Xf6YKo2zKThrZMA2w",
26 "givenName": "Emma",
27 "familyName": "Tasma",
28 "alumniOf": "Zealopia University"
29 },
30 "@context": [
31 "https://www.w3.org/2018/credentials/v1",
32 "https://w3id.org/vc-revocation-list-2020/v1",
33 "https://mattr.global/contexts/vc-extensions/v2",
34 ],
35 "credentialStatus": {
36 "id": "https://learn.vii.au01.mattr.global/core/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f#1",
37 "type": "RevocationList2020Status",
38 "revocationListIndex": "1",
39 "revocationListCredential": "https://learn.vii.au01.mattr.global/core/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f"
40 },
41 "proof": {
42 "type": "Ed25519Signature2018",
43 "created": "2024-01-10T22:54:57Z",
44 "verificationMethod": "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
45 "proofPurpose": "assertionMethod",
46 "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..NgQKScBviBxYE0M2lCS4x8dDZI-eMPo_bMEXyldYGM5k0uh29c0YbgW6xbvzaaioUjbHr3ZUUlq2E8TcOOA9Bg"
47 }
48 },
49 "credentialStatus": {
50 "id": "https://learn.vii.au01.mattr.global/core/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f#1",
51 "type": "RevocationList2020Status",
52 "revocationListIndex": "1",
53 "revocationListCredential": "https://learn.vii.au01.mattr.global/core/v2/credentials/web-semantic/revocation-lists/1fd271b0-55be-4c48-8da0-f4bda929947f"
54 },
55 "issuanceDate": "2024-01-10T22:54:57.083Z"
56}
id
: Unique identifier of the new web credential.tag
: Credential tag, as inserted in the request above.credential
: The credential object contains the following amendments on in addition to the information provided in the request:type
: Every W3C verifiable credential must includeVerifiableCredential
in thetype
property, so MATTR VII also auto-injects this as the first element.issuanceDate
: Timestamp indicating when the credential was signed.@context
: As part of the credential creation MATTR VII will auto-inject the following contexts, which reference the W3C Verifiable Credential definitions (If you require introducing a different context for your production implementation, please contact us):https://w3id.org/vc-revocation-list-2020/v1 (only for revocable credentials).
credentialStatus
: Whenrevocable
is set totrue
in the request, this element includes information that enables future revocation of the credential.proof
: Includes information regarding the encryption algorithm used to sign the credential and how it can be verified.
Branded credentials
The following image depicts how the credential created above would look like once available in the holder's digital wallet. It might help you better understand how to brand your own credential:
Watch this video to learn more about branding best practices.
Check out our Silvereye branding tool to get a real time preview of a credential based your settings and configuration.
What's next?
Now that you have a signed Web Credential, you can encrypt it and then share it with its intended holder.