REST API Server

V1.0

In the section, learn how to programmatically create and issue credentials using the REST API Server.

How it works

The application runs a minimal HTTP server to allow programmatic creation and issuance of credentials. The server can handle REST API requests and provide responses. The server runs on the HTTP protocol on port 58085, the port number can be changed when applicable.

API Authorization

Although the APIs allow requests without authorization, it is highly recommended to set an API Key to secure the server requests. Follow these instructions to set the API Key:

Open the API Server page, and click on the API Security Settings button
In the API Key page, generate an API Key

When making a request to an API, the API Key must be set in the Authorization Bearer place-api-key-here header.

Example of an Authorized Request

POST /api/vc/qrcode/validate HTTP/1.1
Host: localhost:58085
Content-Type: application/json
Authorization: Bearer 0f9c6191df254b93a013ff93aa7355b4
Content-Length: 1030

Starting the Server

In the API Server page, click on the Manage API Server button
On the Server page, click the Start Server button to start the server
The server will start and listen on http://localhost:58085/
The port can be changed if necessary
The server logs for each request and response will be shown in the display window. The server will maintain 250 of the most current logs
To stop the server, click the Stop Server button

Closing the application will automatically shut down the server. Keep the application open to keep the server running.

Create and Issue a PNG Credential

This API creates a PNG credential and issues it to a recipient via an email.

Authorization

If, an API Key is set, place the API Key in the Authorization header of the request.

API Method and Endpoint

Make a POST request to the following endpoint: /api/vc/png/create.

Example POST Request

POST /api/vc/png/create HTTP/1.1
Host: localhost:58085
Content-Type: application/json
Authorization: Bearer 0f9c6191df254b93a013ff93aa7355b4
Content-Length: 265

Request Payload

The request must contain a VerifiableCredentialResource object in JSON format in the body of the request. The properties of this object are shown below:

VerifiableCredentialResource

Property	Type	Required	Note
credentialId	string	yes
credentialName	string	yes
dateIssued	string	yes	1
expiryDate	string	yes	1
recipientName	string	yes
recipientId	string	yes
recipientEmail	string	yes
recipientDateOfBirth	string	no	1
recipientPhoto	string	no	2
isIssuerValid	bool	no
format	string	no

Note 1: All dates must in string format and must comply with dd-MM-yyyy, eg. 24-02-2026

Note 2: The recipient photo must be a Base64-encoded PNG image formatted as a Data URI in string format. The image should be square and between 10-750 kb in size.

Example of Base64-encoded PNG image

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==

Example POST Request

POST /api/vc/png/create HTTP/1.1
Host: localhost:58085
Content-Type: application/json
Authorization: Bearer 0f9c6191df254b93a013ff93aa7355b4
Content-Length: 257

{
    "credentialId" : "C200",
    "credentialName" : "Diploma in Plumbing",
    "dateIssued" : "09-12-2026",
    "expiryDate" : "09-12-2050",
    "recipientName" : "John Doe",
    "recipientId" : "SSN54673",
    "recipientEmail" : "jdoe@mail.com"
}

Response

The API will create a PNG credential and issue the credential to the recipient via the email set in the payload.

Success

A successful response will return a 200 status and the issued VerifiableCredentialResource object in the body of the response in JSON format.

Example of a Response

Response: 200

{
    "credentialId": "C200",
    "credentialName": "Diploma in Plumbing",
    "dateIssued": "09-12-2026",
    "expiryDate": "09-12-2050",
    "recipientName": "John Doe",
    "recipientId": "SSN54673",
    "recipientEmail": "jdoe@mail.com",
    "format": "PNG"
}

Failed

A failed response may contain any of the following status codes, 404, 500, 401. An error message is sent in the body of the response in JSON format.

Example of a Response

Response: 500

{
    "error": "Failed to send email"
}

Validate and Decode a Scanned QR Code Value

This API validates a QR Code value in string format that has been scanned from a credential and returns the decoded credential.

Authorization

If, an API Key is set, place the API Key in the Authorization header of the request.

API Method and Endpoint

Make a POST request to the following endpoint: /api/vc/qrcode/validate.

Example POST Request

POST /api/vc/qrcode/validate HTTP/1.1
Host: localhost:58085
Content-Type: application/json
Authorization: Bearer 0f9c6191df254b93a013ff93aa7355b4
Content-Length: 1030

Request Payload

The request must contain a QRCodeResource object in JSON format in the body of the request. The properties of this object are shown below:

QRCodeResource

Property	Type	Required
scannedValue	string	yes

Example POST Request

POST /api/vc/qrcode/validate HTTP/1.1
Host: localhost:58085
Content-Type: application/json
Authorization: Bearer 0f9c6191df254b93a013ff93aa7355b4
Content-Length: 1030

{
    "scannedValue" : "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImZBWnU3ZXNZa0pWQWVyQW1IT0dITeFJRMXVSLUE1OVNSMXciLCJ5IjoiTjY4LTR4OHZfWURIdlZaRHUxOW9mRDBVamttZnRPanRhYkg3akFYWFJrbyJ9fQ.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiXSwiaWQiOiJ1cm46aWQ6QzEyMzQiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlzc3VlciI6eyJpZCI6ImRpZDprZXk6ekRuYWVZbjdIbzMyaDg1bmZWcnBSMk5iVHNRVHR6SHQyRVlTNWszU1V6a01uZGhhSyIsIm5hbWUiOiJSYXkgQ29uc3VsdGluZyBMaW1pdGVkIiwidmFsaWRVbnRpbCI6IjA2LTExLTIwMjYiLCJ2YWxpZGF0aW9uU2lnbmF0dXJlIjoiQ3JVdEtZN08xZk53YjlHS1cwcVBPaTFPQ2sweU5yU2RrQmZNeDZlZFNxUXBTX0ptVkppclM3RkhScjM0M1hMQldidkd3UGduZ3lxbi1HVWN2ZnBrVGcifSwiiMDQtMDktMjAyNiIsIm5hbWUiOiJTYW1wbGUgUE5HIENyZWRlbnRpYWwiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6InVybjppZDpJRDEyMzQiLCJuYW1lIjoiSm9obiBEb2UiLCJlbWFpbCI6ImFuaWwucmlwbGFAZ21haWwuY29tIn0sInZhbGlkVW50aWwiOiIwNC0wOS0yMDUwIn0.zq4C3TrBRGOaLEQCfixRkGsJnKS5OOJFJnY3N_EG667a7lQKU8plJoCIiONKqi0fXUcxEA"
}

Response

The API will validate the QR Code value and decode it into a VerifiableCredentialResource.

Success

A successful response will return a 200 status and the decoded VerifiableCredentialResource object in the body of the response in JSON format.

Example of a Response

Response: 200

{
    "isIssuerValid": true,
    "credentialId": "urn:id:C200",
    "credentialName": "Diploma in Plumbing",
    "dateIssued": "09-12-2026",
    "expiryDate": "09-12-2050",
    "recipientName": "John Doe",
    "recipientId": "SSN54673",
    "recipientEmail": "jdoe@mail.com"
}

Failed

A failed response may contain any of the following status codes, 404, 500, 401. An error message is sent in the body of the response in JSON format.

Example of a Response

Response: 500

{
    "error": "Invalid signature"
}