Learn

JSON credentials configuration

Create a JSON credentials configuration

Creates a new JSON credentials configuration, a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

The credential configuration payload

name
required
string [ 1 .. 1024 ] characters

Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder's digital wallet. It is recommended to limit this value to 18 characters as any additional characters are not displayed on the credential.

description
string <= 1024 characters

Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder's digital wallet. It is recommended to limit this value to 38 characters as any additional characters are not displayed on the credential.

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different JSON credentials configurations on your tenant. Thus, its value must:

  • Be unique across all JSON credentials configurations on your tenant.
  • Not be VerifiableCredential.
additionalTypes
Array of strings

Additional credential types that can be referenced. Each entry must be 1-1024 characters long, with no whitespaces allowed.

contexts
Array of strings

Additional JSON-LD contexts to be included in the credential. As part of the credential issuance MATTR VII will auto-inject the following contexts, which reference the W3C Verifiable Credential definitions:

required
object

Issuer details and branding for issued credentials. Refer to this video to learn more about branding best practices.

proofType
string

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 and 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.
Enum: "Ed25519Signature2018" "BbsSignature2022"
object

Additional branding that will be applied to issued credentials. Refer to this video to learn more about branding best practices.

object

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.

Example claims object inside the user object

{
  "claims": {
    "given_name": "Jamie",
    "family_name": "Doe",
    "address": {
      "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
    }
  },
  "authenticationProvider": {
    "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
    "url": "https://accounts.google.com"
  }
}
persist
boolean
Default: false

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:

  • id
  • tag
  • credentialStatus
  • issuanceDate
revocable
boolean
Default: true

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
boolean
Default: false

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
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Responses
201

JSON credentials configuration created

400

Bad Request

post/core/v2/credentials/web-semantic/configurations
Request samples
application/json
{
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}
Response samples
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Retrieve all JSON credentials configurations

Returns a list of all JSON credential configurations on your tenant.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
type
string

The optional credential type to filter on

Example: type=AlumniCredential
Responses
200

JSON credentials configurations retrieved

400

Bad Request

get/core/v2/credentials/web-semantic/configurations
Request samples 
Response samples 
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}
Retrieve a JSON credentials configuration
Retrieve a JSON credentials configuration by providing its ID.


Analytic events


    

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_START
    • 

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_SUCCESS
    • 

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
JSON credentials configuration unique identifier


 
 Example:  3948c40e-6e19-4ffc-933c-91f643f24264
Responses 
200
JSON credentials configuration retrieved


400
Bad Request


404
The credential configuration is not found


get/core/v2/credentials/web-semantic/configurations/{id}
Request samples 
Response samples 
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}
Update a JSON credentials configuration
Updates an existing JSON credentials configuration by providing its ID.


Analytic events


    

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_START
    • 

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_SUCCESS
    • 

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
JSON credentials configuration unique identifier


 
 Example:  3948c40e-6e19-4ffc-933c-91f643f24264
Request Body schema: application/json
required
Update a credential configuration


name
required
string  [ 1 .. 1024 ] characters 
Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder's digital wallet. It is recommended to limit this value to 18 characters as any additional characters are not displayed on the credential.


 
description
string  <= 1024 characters 
Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder's digital wallet. It is recommended to limit this value to 38 characters as any additional characters are not displayed on the credential.


 
type
required
string  [ 1 .. 1024 ] characters 
Used to differentiate between different JSON credentials configurations on your tenant. Thus, its value must:


    

  • Be unique across all JSON credentials configurations on your tenant.
    • 

  • Not be VerifiableCredential.
    • 



 
additionalTypes
Array of strings
Additional credential types that can be referenced. Each entry must be 1-1024 characters long, with no whitespaces allowed.


 
contexts
Array of strings
Additional JSON-LD contexts to be included in the credential. As part of the credential issuance MATTR VII will auto-inject the following contexts, which reference the W3C Verifiable Credential definitions:



 
required
object
Issuer details and branding for issued credentials. Refer to this video to learn more about branding best practices.


 
proofType
string
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 and 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.
    • 



 Enum: "Ed25519Signature2018" "BbsSignature2022"  
object
Additional branding that will be applied to issued credentials. Refer to this video to learn more about branding best practices.


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



Example claims object inside the user object


{
  "claims": {
    "given_name": "Jamie",
    "family_name": "Doe",
    "address": {
      "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
    }
  },
  "authenticationProvider": {
    "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
    "url": "https://accounts.google.com"
  }
}



 
persist
boolean
 Default:  false
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:


    

  • id
    • 

  • tag
    • 

  • credentialStatus
    • 

  • issuanceDate
    • 



 
revocable
boolean
 Default:  true
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
boolean
 Default:  false
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
string <uuid> 
References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.


 
object
Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.


 
Responses 
200
JSON credentials configuration updated


400
Bad Request


404
The credential configuration is not found


put/core/v2/credentials/web-semantic/configurations/{id}
Request samples 
application/json
{
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}
Response samples 
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}
Delete a JSON credentials configuration
Deletes an existing JSON credentials configuration by providing its ID.


Analytic events


    

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_START
    • 

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_SUCCESS
    • 

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
JSON credentials configuration unique identifier


 
 Example:  3948c40e-6e19-4ffc-933c-91f643f24264
Responses 
204
JSON credentials configuration deleted


400
Bad Request


404
The credential configuration is not found


delete/core/v2/credentials/web-semantic/configurations/{id}
Request samples 
Response samples 
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}
➔ Next to mDoc credentials configuration