JSON Credentials
Create a JSON Credential 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
/v2/credentials/web-semantic/configurations
In: header
The credential configuration payload
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.
1 <= length <= 1024
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.
length <= 1024
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
.
1 <= length <= 1024
Additional credential types that can be referenced. Each entry must be 1-1024 characters long, with no whitespaces allowed.
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:
- https://www.w3.org/2018/credentials/v1
- https://mattr.global/contexts/vc-extensions/v2
- https://w3id.org/vc-revocation-list-2020/v1 If you require introducing a different context for your production implementation, please contact us. Referenced contexts must be whitelisted or credential issuance will fail.
Issuer details and branding for issued credentials. Refer to this video to learn more about branding best practices.
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 aBbsSignature2022
proof. Credentials signed with this proof type support selective disclosure. - If a
Bls12381G2
key is unavailable and 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.
"Ed25519Signature2018" | "BbsSignature2022"
Additional branding that will be applied to issued credentials. Refer to this video to learn more about branding best practices.
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.
- When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g.
defaultValue
: Indicates what value is used if required 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. Exampleclaims
object inside theuser
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"
}
}
Empty Object
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
false
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.
true
References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.
uuid
Used to determine when will issued credentials expire. Can include any combination of years
, months
, weeks
, days
, hours
, minutes
and seconds
.
curl -X POST "https://example.vii.au01.mattr.global/v2/credentials/web-semantic/configurations" \ -H "Content-Type: application/json" \ -d '{}'
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"name": "Course credential",
"description": "This credential shows that the person has attended a course.",
"type": "CourseCredential",
"additionalTypes": [
"AlumniCredential",
"EducationCredential"
],
"contexts": [
"https://optionalschema.example/"
],
"issuer": {
"name": "ABC University",
"logoUrl": "https://example.edu/img/logo.png",
"iconUrl": "https://example.edu/img/icon.png"
},
"proofType": "Ed25519Signature2018",
"credentialBranding": {
"backgroundColor": "#B00AA0",
"watermarkImageUrl": "https://example.edu/img/watermark.png"
},
"claimMappings": {
"firstName": {
"mapFrom": "claims.given_name",
"required": true
},
"address": {
"mapFrom": "claims.address.formatted"
},
"picture": {
"mapFrom": "claims.picture",
"defaultValue": "http://example.edu/img/placeholder.png"
},
"badge": {
"defaultValue": "http://example.edu/img/badge.png"
},
"providerSubjectId": {
"mapFrom": "authenticationProvider.subjectId"
}
},
"persist": false,
"revocable": true,
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 3,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
}
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Retrieve all JSON Credential configurations
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
/v2/credentials/web-semantic/configurations
In: header
Query Parameters
Range size of returned list.
100
1 <= value <= 1000
Starting point for the list of entries.
The optional credential type to filter on
curl -X GET "https://example.vii.au01.mattr.global/v2/credentials/web-semantic/configurations?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h&type=AlumniCredential"
{
"nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
"data": [
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"name": "Course credential",
"description": "This credential shows that the person has attended a course.",
"type": "CourseCredential",
"additionalTypes": [
"AlumniCredential",
"EducationCredential"
],
"contexts": [
"https://optionalschema.example/"
],
"issuer": {
"name": "ABC University",
"logoUrl": "https://example.edu/img/logo.png",
"iconUrl": "https://example.edu/img/icon.png"
},
"proofType": "Ed25519Signature2018",
"credentialBranding": {
"backgroundColor": "#B00AA0",
"watermarkImageUrl": "https://example.edu/img/watermark.png"
},
"claimMappings": {
"firstName": {
"mapFrom": "claims.given_name",
"required": true
},
"address": {
"mapFrom": "claims.address.formatted"
},
"picture": {
"mapFrom": "claims.picture",
"defaultValue": "http://example.edu/img/placeholder.png"
},
"badge": {
"defaultValue": "http://example.edu/img/badge.png"
},
"providerSubjectId": {
"mapFrom": "authenticationProvider.subjectId"
}
},
"persist": false,
"revocable": true,
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 3,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
}
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Retrieve a JSON Credential configuration
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
/v2/credentials/web-semantic/configurations/{id}
In: header
Path Parameters
JSON credentials configuration unique identifier
uuid
curl -X GET "https://example.vii.au01.mattr.global/v2/credentials/web-semantic/configurations/3948c40e-6e19-4ffc-933c-91f643f24264"
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"name": "Course credential",
"description": "This credential shows that the person has attended a course.",
"type": "CourseCredential",
"additionalTypes": [
"AlumniCredential",
"EducationCredential"
],
"contexts": [
"https://optionalschema.example/"
],
"issuer": {
"name": "ABC University",
"logoUrl": "https://example.edu/img/logo.png",
"iconUrl": "https://example.edu/img/icon.png"
},
"proofType": "Ed25519Signature2018",
"credentialBranding": {
"backgroundColor": "#B00AA0",
"watermarkImageUrl": "https://example.edu/img/watermark.png"
},
"claimMappings": {
"firstName": {
"mapFrom": "claims.given_name",
"required": true
},
"address": {
"mapFrom": "claims.address.formatted"
},
"picture": {
"mapFrom": "claims.picture",
"defaultValue": "http://example.edu/img/placeholder.png"
},
"badge": {
"defaultValue": "http://example.edu/img/badge.png"
},
"providerSubjectId": {
"mapFrom": "authenticationProvider.subjectId"
}
},
"persist": false,
"revocable": true,
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 3,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
}
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Update a JSON Credential configuration
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
/v2/credentials/web-semantic/configurations/{id}
In: header
Path Parameters
JSON credentials configuration unique identifier
uuid
Update a credential configuration
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.
1 <= length <= 1024
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.
length <= 1024
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
.
1 <= length <= 1024
Additional credential types that can be referenced. Each entry must be 1-1024 characters long, with no whitespaces allowed.
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:
- https://www.w3.org/2018/credentials/v1
- https://mattr.global/contexts/vc-extensions/v2
- https://w3id.org/vc-revocation-list-2020/v1 If you require introducing a different context for your production implementation, please contact us. Referenced contexts must be whitelisted or credential issuance will fail.
Issuer details and branding for issued credentials. Refer to this video to learn more about branding best practices.
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 aBbsSignature2022
proof. Credentials signed with this proof type support selective disclosure. - If a
Bls12381G2
key is unavailable and 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.
"Ed25519Signature2018" | "BbsSignature2022"
Additional branding that will be applied to issued credentials. Refer to this video to learn more about branding best practices.
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.
- When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g.
defaultValue
: Indicates what value is used if required 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. Exampleclaims
object inside theuser
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"
}
}
Empty Object
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
false
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.
true
References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.
uuid
Used to determine when will issued credentials expire. Can include any combination of years
, months
, weeks
, days
, hours
, minutes
and seconds
.
curl -X PUT "https://example.vii.au01.mattr.global/v2/credentials/web-semantic/configurations/3948c40e-6e19-4ffc-933c-91f643f24264" \ -H "Content-Type: application/json" \ -d '{}'
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"name": "Course credential",
"description": "This credential shows that the person has attended a course.",
"type": "CourseCredential",
"additionalTypes": [
"AlumniCredential",
"EducationCredential"
],
"contexts": [
"https://optionalschema.example/"
],
"issuer": {
"name": "ABC University",
"logoUrl": "https://example.edu/img/logo.png",
"iconUrl": "https://example.edu/img/icon.png"
},
"proofType": "Ed25519Signature2018",
"credentialBranding": {
"backgroundColor": "#B00AA0",
"watermarkImageUrl": "https://example.edu/img/watermark.png"
},
"claimMappings": {
"firstName": {
"mapFrom": "claims.given_name",
"required": true
},
"address": {
"mapFrom": "claims.address.formatted"
},
"picture": {
"mapFrom": "claims.picture",
"defaultValue": "http://example.edu/img/placeholder.png"
},
"badge": {
"defaultValue": "http://example.edu/img/badge.png"
},
"providerSubjectId": {
"mapFrom": "authenticationProvider.subjectId"
}
},
"persist": false,
"revocable": true,
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 3,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
}
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Delete a JSON Credential configuration
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
/v2/credentials/web-semantic/configurations/{id}
In: header
Path Parameters
JSON credentials configuration unique identifier
uuid
curl -X DELETE "https://example.vii.au01.mattr.global/v2/credentials/web-semantic/configurations/3948c40e-6e19-4ffc-933c-91f643f24264"
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "NotFound",
"message": "Validation Error",
"details": [
{
"location": "params",
"msg": "Resource Not Found",
"param": "id",
"value": "638c5634-fb06-403a-bb00-ddb867ea9063"
}
]
}
How would you rate this page?