Create Credential Templates
Once the organisation has been set up and validated credential templates can be created in Condatis Credential Gateway.
Separate credential templates must be created for issuance and verification.
Create template for issuing credentials
An issuance credential template is required to configure the verifiable credentials that your organisation issues. The template creation manages details such as the credential attributes that are configured, and the creation of the credential DIDs and any other properties that need to be registered for the VC Ecosystem.
Information required to create issuance credential templates
Create issuance credential template request endpoint
POST /api/Organisation/{organisationId}/credentialtemplate
Create issuance credential template request headers
Header | Value |
---|---|
Authorization | Bearer access_token |
Create issuance credential template request URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
organisationId | string | Yes | The ID of your organisation. |
The organisationId
is required to know which organisation the credential template belongs to, and is also used in the naming convention.
Create issuance credential template request body parameters
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Yes | The name of your credential template for ease of identification. |
type | int | Yes | The type of credential template to create - in this case Issuance. |
attributeNames | string | Yes | The array of the attribute names configured for your credential. The SerialNumber is required. |
microsoft | MicrosoftIssuanceTemplate |
No | Microsoft agent specific template used to configure credential type and the attribute name map. |
logo | string | No | The logo to be used for this specific credential. If this value is null, then the value set at the organisation level will be used instead. |
primaryColor | string | No | The primary color to be used for this specific credential. If this value is null, then the value set at the organisation level will be used instead. |
secondaryColor | string | No | The secondary color to be used for this specific credential. If this value is null, then the value set at the organisation level will be used instead. |
credentialInstructions | string | No | The credential instructions to be used for this specific credential. If this value is null, then the value set at the organisation level will be used instead. |
MicrosoftIssuanceTemplate
Property | Type | Required | Description |
---|---|---|---|
credentialType | string | Yes | The name of the credential type that your credential will be based on. |
attributeMapping | string | No | The array of attribute type mappings for your credential. This is optional but any entries must exist in the attributeNames property. It allows Type ("string" or "image/jpg;base64url") and Label (displayed in the wallet) to be defined for an attribute. |
Create issuance credential template request body
POST {{GatewayHubUrl}}/api/organisation/{{OrganisationId}}/credentialTemplate
Authorization: Bearer {{accessToken}}
Content-Type: application/json
{
"name": "{{CredentialType}}",
"type": "Issuance",
"attributeNames": [
"additionalProp1",
"additionalProp2",
"SerialNumber",
"ExpiresAt"
],
"microsoft": {
"credentialType": "{{CredentialType}}",
},
"logo": "{{CredentialTemplateLogo}}",
"primaryColor": "{{CredentialTemplatePrimaryColor}}",
"secondaryColor": "{{CredentialTemplateSecondaryColor}}",
"credentialInstructions": "{{CredentialTemplateCredentialInstructions}}"
}
The settings {{Name}}, etc will need to be updated as appropriate in the request body, as illustrated in the following example.
{
"name": "TestCredential",
"type": "Issuance",
"attributeNames": [
"TestAttribute1",
"TestAttribute2",
"TestAttribute3",
"SerialNumber",
"ExpiresAt"
],
"microsoft": {
"credentialType": "TestCredential",
"attributeMapping": {
"TestAttribute1" : {
"Label": "Test Attribute 1"
},
"TestAttribute2" : {
"Type": "String",
"Label": "Test Attribute 2"
},
"TestAttribute3": {
"Type": "image/jpg;base64url"
}
}
},
"logo": "https://robohash.org/condatis/?set=set4",
"primaryColor": "#FFF",
"secondaryColor": "#000",
"credentialInstructions": "Please accept this credential to your wallet."
}
Create issuance credential template request returns
A successful call will return the created credential template as a JSON file. The call creates the template's ID value which is used as a parameter in the supportedTemplateIds
property when creating a client.
{
"name": "string",
"type": "string",
"attributeNames": [
"string"
],
"id": "string",
"organisationId": "string",
"microsoft": {
"credentialType": "string",
"attributeNameMap": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"contractUri": "uri",
"contractId": "guid"
},
"credentialMapType": null,
"logo": "string",
"primaryColor": "string",
"secondaryColor": "string",
"credentialInstructions": "string"
}
An unsuccessful call will return a 400 Bad Request or 404 Not Found status code, and an error message which should highlight the parameter(s) that needs checking.
{
"type": "string",
"title": "string",
"status": 0,
"traceId": "string",
"errors": {
"additionalProp1": [
"string"
],
"additionalProp2": [
"string"
]
}
}
Sample success response (201)
Based on the example body above, the JSON object below shows what a successful response looks like with populated values.
{
"id": "bd816d9c-9259-4069-a401-t351gc1b1023-TestCredential-IssuanceCredentialTemplate",
"organisationId": "bd816d9c-9259-4069-a401-t351gc1b1023",
"name": "TestCredential",
"type": "Issuance",
"attributeNames": [
"TestAttribute1",
"TestAttribute2",
"TestAttribute3",
"SerialNumber",
"ExpiresAt"
],
"logo": "https://robohash.org/condatis/?set=set4",
"primaryColor": "#FFF",
"secondaryColor": "#000",
"credentialInstructions": "Please accept this credential to your wallet.",
"microsoft": {
"credentialType": "TestCredential",
"attributeMapping": {
"TestAttribute1" : {
"Label": "Test Attribute 1"
},
"TestAttribute2" : {
"Type": "String",
"Label": "Test Attribute 2"
},
"TestAttribute3": {
"Type": "image/jpg;base64url"
}
}
}
}
Sample unsuccessful response (400)
If any values are invalid or missing, an error response will be returned with a message highlighting the area that needs checking.
In this example, the credential template cannot be created as there may be one that already exists with the same name. The error message returned shows that in the errors
property.
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"credentialTemplate": [
"Unable to create a new credential template, a credential template with the same name and type may already exist."
]
}
}
In this example, the SerialNumber
, which is required, is missing information in the attributesNames
property.
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"AttributeNames": [
"Unable to create new credential template as no SerialNumber attribute found in attributeNames."
]
}
}
Sample not found response (404)
In the case that the organisationId
is missing or incorrect, an error message response will be returned.
HTTP/1.1 404 Not Found
"Unable to retrieve the organisation with ID 00000000-0000-0000-0000-000000000000."
Create template for issuing credentials
A verification credential template is required to configure the verifiable credentials that your organisation verifies. The template call manages details such as restricting which credential attributes are verified during a presentation, multiple verification credential templates can be passed during the verification calls which allows for multiple credentials to be verified at once.
Information required to create verification credential templates
Create verification credential template request endpoint
POST /api/Organisation/{organisationId}/credentialtemplate
Create verification credential template request headers
Header | Value |
---|---|
Authorization | Bearer access_token |
Create verification credential template request URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
organisationId | string | Yes | The ID of your organisation. |
The organisationId
is required to know which organisation the credential template belongs to, and is also used in the naming convention.
Create verification credential template request body parameters
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Yes | The name of your credential template for ease of identification. |
type | int | Yes | The type of credential template to create - in this case Verification. |
attributeNames | string | Yes | The array of the attribute names configured for your credential. The SerialNumber is required. |
microsoft | MicrosoftVerificationTemplate |
No | Microsoft agent specific template used to configure credential type and the attribute name map. |
MicrosoftVerificationTemplate
Parameter | Type | Required | Description |
---|---|---|---|
credentialType | string | Yes | The name of the credential type that your credential will be based on. |
attributeNameMap | string | No | The mapped array of configured attribute names for your credential. If not provided this is generated automatically from the attributeNames parameters and CredentrialType. |
Create verification credential template request body
POST {{GatewayHubUrl}}/api/organisation/{{OrganisationId}}/credentialTemplate
Authorization: Bearer {{accessToken}}
Content-Type: application/json
{
"name": "{{CredentialType}}",
"type": "Verification",
"attributeNames": [
"additionalProp1",
"additionalProp2",
"SerialNumber",
"ExpiresAt"
],
"microsoft": {
"credentialType": "{{CredentialType}}",
}
}
The settings {{Name}}, etc will need to be updated as appropriate in the request body, as illustrated in the following example.
{
"name": "TestCredential",
"type": "Verification",
"attributeNames": [
"TestAttribute1",
"TestAttribute2",
"TestAttribute3",
"SerialNumber",
"ExpiresAt"
],
"microsoft": {
"credentialType": "TestCredential"
}
}
Create verification credential template request returns
A successful call will return a 201 Created status code and the created credential template as a JSON file. The call creates the template's ID value which is used as a parameter in the supportedTemplateIds
property when creating a client.
{
"name": "string",
"type": 0,
"attributeNames": [
"string"
],
"id": "string",
"organisationId": "string",
"microsoft": {
"credentialType": "string",
"attributeNameMap": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
}
An unsuccessful call will return a 400 Bad Request or 404 Not Found status code, and an error message which should highlight the parameter(s) that needs checking.
{
"type": "string",
"title": "string",
"status": 0,
"traceId": "string",
"errors": {
"additionalProp1": [
"string"
],
"additionalProp2": [
"string"
]
}
}
Sample success response (201)
Based on the example body above, the JSON object below shows what a successful response looks like with populated values.
{
"id": "bd816d9c-9259-4069-a401-t351gc1b1023-TestCredential-VerificationCredentialTemplate",
"organisationId": "bd816d9c-9259-4069-a401-t351gc1b1023",
"microsoft": {
"credentialType": "TestCredential",
"attributeNameMap": null
}, "name": "TestCredential",
"type": "Verification",
"attributeNames": [
"TestAttribute1",
"TestAttribute2",
"TestAttribute3",
"SerialNumber",
"ExpiresAt"
]
}
Sample unsuccessful response (400)
If any values are invalid or missing, an error response will be returned with a message highlighting the area that needs checking.
In this example, the credential template cannot be created as there may be one that already exists with the same name. The error message returned shows that in the errors
property.
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"credentialTemplate": [
"Unable to create a new credential template, a credential template with the same name and type may already exist."
]
}
}
In this example, the SerialNumber
, which is required, is missing information in the attributesNames
property.
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"AttributeNames": [
"Unable to create new credential template as no SerialNumber attribute found in attributeNames."
]
}
}
Sample not found response (404)
In the case that the organisationId
is missing or incorrect, an error message response will be returned.
HTTP/1.1 404 Not Found
"Unable to retrieve the organisation with ID 00000000-0000-0000-0000-000000000000."