Create Credential Templates

Once the organisation has been set up and validated credential templates can be created in Cenda.

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

Using the Management Portal

  1. Click "Credential Templates" on the navigation bar.
  2. Select the organisation you want to create a Credential Template for.
  3. Click "Create New Credential Template".
  4. For "Template Type", select "Issuance".
  5. Add at least one attribute.
  • There must exist an attribute called "SerialNumber".
  • An authenticator label can be specified for every attribute.
  • The data type for any attribute can be a "String", or a "JpegImageType" if the attribute refers to an image in base64 encoding.

  1. Fill out the required fields, as denoted by *.

  2. Click Submit. You will be redirected to view the details of this new Credential Template if the Credential Template has been created successfully. If an error occurs, you will be referred to an error page, which will state the reason for the error where possible.

Using a REST API Client

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.
validForDays int No The number of days an issued credential will be valid for. Must be a positive integer.
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 mappings for your credential. This is optional but any entries must exist in the attributeNames property. It allows Type ("string" or "image/jpg;base64url"), Label (displayed in the wallet), Attestation (IdTokenHint or SelfAsserted) and Required (boolean) to be defined for an attribute.
pinCodeLength integer No When provided defines the length of a Pin Code that can be used for issuance. The allowed values are 4 to 16 inclusive.

The Attestation field in the attributeMapping allows the source of credential data to be defined. IdTokenHint is the default and means that the credential data to issue must be provided in an IdTokenHint (see OIDC Interface Definition for details). SelfAsserted indicates that the user will be prompted to input data in their Identity Wallet App during issuance.

Screenshot of the attributes in the MS Authenticator app.

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",
    "ExpiryDate"
  ],
  "microsoft": {
    "credentialType": "{{CredentialType}}",
  },
  "logo": "{{CredentialTemplateLogo}}",
  "primaryColor": "{{CredentialTemplatePrimaryColor}}",
  "secondaryColor": "{{CredentialTemplateSecondaryColor}}",
  "credentialInstructions": "{{CredentialTemplateCredentialInstructions}}",
  "validForDays": "{{ValidForDays}}"
}

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",
    "ExpiryDate"
  ],
  "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.",
  "validForDays": "365"
}
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",
    "attributeMapping": {
      "attribute1": "attributeMappingDetails",
      "attribute2": "attributeMappingDetails",
      "attribute3": "attributeMappingDetails"
    },
    "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 verifying 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

Using the Management Portal

  1. Click "Credential Templates" on the navigation bar.
  2. Select the organisation you want to create a Credential Template for.
  3. Click "Create New Credential Template".
  4. For "Template Type", select "Verification".
  5. Add at least one attribute.
  • A claims label can be specified for every attribute.

  1. Fill out the required fields, as denoted by *.

  2. Click Submit. You will be redirected to view the details of this new Credential Template if the Credential Template has been created successfully. If an error occurs, you will be referred to an error page, which will state the reason for the error where possible.

Using a REST API Client

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.
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 CredentialType.
isFaceCheckEnabled boolean No A boolean that determines if the FaceCheck feature is enabled for this credential and should be presented to the user during verification on the Microsoft Authenticator.
sourcePhotoClaimName string No (Yes, if FaceCheck enabled) The claim within the credential that will be the photo to compare the verifier's face to during the FaceCheck process. Note: The value for this is case sensitive and must match exactly to the claim name value.
matchConfidenceThreshold int No The confidence score (probability percentage) that the likelihood the photo matches the user captured in the mobile device required to be met for the face check to pass. A value between 50 and 100, if a value is not included then it will be the Microsoft default of 70.

A screenshot showing the attributes after a successful verification.

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

Facecheck (Microsoft configured organisations)

Enable facecheck for authority endpoint

To enable facecheck on Microsoft configured organisations, a request to the "Enable Facecheck" endpoint must be made. This will make a request to the Microsoft Management API to enable the associated authority to use the facecheck feature of the Microsoft Authenticator.

Note: The organisation must exist and be validated to be face check enabled.

POST {{GatewayHubUrl}}/api/organisation/{{OrganisationId}}/enablefacecheck
Authorization: Bearer {{accessToken}}
Content-Type: application/json

The response from this call will be a 200 OK.