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:
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/configurations
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 "claimSourceId": "945214ad-3635-4aff-b51d-61d69a3c8eee",
40 "expiresIn": {
41 "months": 12
42 }
43}
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 thename
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 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.
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 whenlogoURL
is not provided. WheniconURL
is not provided, the first letter fromname
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 whendefaultValue
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 ifrequired
is set tofalse
(field is optional) and no value is provided by the claims source. WhendefaultValue
is provided,mapFrom
is optional.required
: Indicates whether the claim is required (default:false
). When a required claim cannot be retrieved and nodefaultValue
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 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.
persist
: When set totrue
, both the issued credential and its metadata are stored in the credential registry. When set tofalse
(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 totrue
(default), 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 used to manage revocation status.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 ofyears
,months
,weeks
,days
,hours
,minutes
andseconds
.
Response
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.
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:
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.