Learn

Create a Web Credential configuration

You can also create a Web Credential configuration via our Self service portal.

Request

Make a request of the following structure to create a new Web Credential configuration:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/configurations
json
Copy to clipboard.
1{
2    "name": "Computer Science Course Credential",
3    "description": "Diploma in Management",
4    "type": "CourseCredential",
5    "additionalTypes": [
6        "EducationCredential"
7    ],
8    "issuer": {
9        "name": "Kakapo University",
10        "logoUrl": "https://example.edu/img/logo.png",
11        "iconUrl": "https://example.edu/img/icon.png"
12    },
13    "credentialBranding": {
14        "backgroundColor": "#860012",
15        "watermarkImageUrl": "https://example.edu/img/watermark.png"
16    },
17    "claimMappings": {
18        "firstName": {
19            "mapFrom": "claims.firstName",
20            "required": true
21        },
22        "address": {
23            "mapFrom": "claims.address.formatted"
24        },
25        "picture": {
26            "mapFrom": "claims.picture",
27            "defaultValue": "http://example.edu/img/placeholder.png"
28        },
29        "badge": {
30            "defaultValue": "http://example.edu/img/badge.png"
31        },
32        "providerSubjectId": {
33            "mapFrom": "authenticationProvider.subjectId"
34        }
35    },
36    "proofType": "Ed25519Signature2018",
37    "persist": false,
38    "revocable": true,
39    "includeId": true,
40    "claimSourceId": "945214ad-3635-4aff-b51d-61d69a3c8eee",
41    "expiresIn": {
42      "months": 12
43    }
44}

  • 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.

  • description : Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder's digital wallet (see image below). Maximum length is 38 characters.

  • type (required): Used to differentiate between different Web credential configurations on your tenant. Thus, its value must:

    • Be unique across all Web credential configurations on your tenant.

    • Not be VerifiableCredential.

  • additionalTypes (optional): Additional credential types that can be referenced.

  • issuer: Issuer details to be displayed on issued credentials:

    • 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 when logoURL 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's name and iconURL 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.

      • Recommended maximum size for logoURL is 50 KB.

      • 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 when logoURL is not provided. When iconURL 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.

      • Recommended maximum size for iconURL is 15 KB.

      • Refer to this video to learn more about branding best practices.

  • credentialBranding: Additional branding that will be applied to issued credentials:

    • 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.

    • If no watermark image is provided, a wave pattern is applied to the credentials by default.

    • Recommended maximum size for watermarkImageUrl is 150 KB.

    • Refer to this video to learn more about branding best practices.

  • claimMappings: This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

    • mapFrom: References the path in the user object where the claim is available.

      • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").

      • mapFrom is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.

    • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.

    • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail.

    Refer to Credential configuration claims to learn more about how this object is created and handled.

  • proofType (optional): 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 no proofType 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 a BbsSignature2022 proof. Credentials signed with this proof type support selective disclosure.

    • If a Bls12381G2 key is unavailable, but a Ed25519 key is available, the credential will be signed with a Ed25519Signature2018 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.

  • persist: When set to true, both the issued credential and its metadata are stored in the credential registry. When set to false (default) 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 to true (default), the created credential can later be revoked. When set to false, the credential cannot be revoked. When set to true, 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 the credentialStatus object used to manage revocation status.

  • includeId: When set to true, the signed credential identifier is included in both the credential object and the credential metadata. When set to false it is only included in the credential metadata.

  • claimSourceId (optional): References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

  • expiresIn (optional): Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Response

json
Copy to clipboard.
1{
2   "id": "983c0a86-204f-4431-9371-f5a22e506599",
3   "name": "Computer Science Course Credential",
4   "description": "Completed the Computer Science course at Kakapo University",
5   //... rest of your credential configuration
6}

  • id: Uniquely identifies the created credential configuration. This identifier can be used to create an offer based on this credential configuration, or to retrieve, update or remove the credential configuration.

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. These must be whitelisted or credential issuance will fail. In-line context definitions would also result in an error.

Branded credential

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:

https://www.datocms-assets.com/38428/1704936881-branding.png?auto=format

  • 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 created a credential configuration, you can proceed to create a credential offer based on this configuration.