Badges API

Build or integrate into your solution by using BWS Blockchain Badges API.

Add Issuer

An issuer is an entity or organization responsible for defining, creating, and awarding digital badges to recognize and verify an individual's achievements, skills, or competencies.

Use this API operation to create a new Issuer that will be enabled to create digital badges and awards.

new_issuer

POST https://api.bws.ninja/v1/call

Use this operation to create a new badge Issuer.

Request Body

Name	Type	Description

200 Returns the issuer ID

{
    "statusCode": 200,
    "info": {
        "issuerId": "https://badges.staging.bws.ninja/certify-badge/issuer/a68d1d72-1365-4114-8349-0b2e220f43e3"
    }
}

Add Issuer Parameters

Use an email address you have access to! To verify your permission to use the provided email, we will send a verification email (How to Verify a Badge Issuer).

Parameter	Type	Desciption

Add Issuer API call example

Add Issuer API call using Node.js

const axios = require('axios');

/* build request to use BWS Badges solution */
const request = {
{
  "solution": "BWS.Blockchain.Badges",
  "operation": "new_issuer",
  "parameters":  {
     "name": "Cloud Academy",
     "url": "https://mycloudacademywebsiteurl.com",
     "email": "[e-mail]"      
  }
}

/* call BWS API using Axios */
let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.bws.ninja/v1/call',
  headers: { 
    'X-Api-Key': 'XqaLg...... A5k2V729v', /* use your API key here! */
    'Content-Type': 'application/json'
  },
  data : JSON.stringify(request)
};

axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Add Issuer call response

When the API call is successfully executed, it returns the badge issuerId, which is also the url you can use to fetch the issuer Open Badge v2.0 JSON.

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://badges.staging.bws.ninja/certify-badge/issuer/a68d1d72-1365-4114-8349-0b2e220f43e3"
  }
}

How to verify a Badge Issuer

When you create a new Badge Issuer, we send an email for verification, including a verification link and a verification code.

Badge Issuer verification Email example.

To verify an Issuer, you - or someone with access to the provided email inbox - should click on the verification link or send you the verification code (once you get the code, use the Verify Badge Issuer API call to verify the issuer).

Verify Issuer

To legitimate badge issuers, we send a verification link and code to the address you use when adding a new badge issuer.

Only verified issuers can create and award badges.

Only verified issuers can create and award badges, ensuring high trust and authenticity in the digital credentialing system.

Use the following operation to verify an issuer using the provided code.

verify_issuer

POST https://api.bws.ninja/v1/call

Use this operation to verify a badge issuer using the code received by email.

Request Body

Name	Type	Description

200 Standard 200 response

{
    "statusCode": 200
}

Verify Issuer Parameters

Parameter	Type	Desciption

Verify Issuer API call example

Verify Issuer using Node.js

const axios = require('axios');

/* build request to use BWS Badges solution */
const request = {
{
  "solution": "BWS.Blockchain.Badges",
  "operation": "verify_issuer",
  "parameters":  {
     "issuerId": "https://badges.staging.bws.ninja/certify-badge/issuer/a68d1d72-1365-4114-8349-0b2e220f43e3",
     "code": "THFJD"         
  }
}

/* call BWS API using Axios */
let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.bws.ninja/v1/call',
  headers: { 
    'X-Api-Key': 'XqaLg...... A5k2V729v', /* use your API key here! */
    'Content-Type': 'application/json'
  },
  data : JSON.stringify(request)
};

axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Verify Issuer call response

When the API call is successfully executed and the issuer gets verified, you will get a 200 status code.

{
  "statusCode": 200
  "info": "issuer has been verified"
}

List Issuers

Use this operation to get the list of issuers you created.

list_issuers

POST https://api.bws.ninja/v1/call

Get the list of your Badges.

Request Body

Name	Type	Description

200 The list of issuers you created.

{
 "statusCode": 200,
 "info": [
    {
       "@context": "https://w3id.org/openbadges/v2",
       "type": "Issuer",
       "id": "https://badges.staging.bws.ninja/certify-badge/issuer/105c00ba-3c18-4d49-938c-566e60d25537",
       "name": "Blockchain Web Services",
       "url": "https://www.bws.ninja",
       "email": "[e-mail]"     
   }
 ]
}

List Issuers API call example

List Issuers using cURL

curl --location 'https://api.staging.bws.ninja/v1/call' \
--header 'X-Api-Key: XqaLg...729v' \
--header 'Content-Type: application/json' \
--data '{
    "solution": "BWS.Blockchain.Badges",
    "operation": "list_issuers"
}'

List Issuers call response

Once executed correctly, you will get a list of your account issuers.

{
 "statusCode": 200,
 "info": [
   {
      "@context": "https://w3id.org/openbadges/v2",
      "id": "https://badges.staging.bws.ninja/certify-badge/issuer/d9623c7f-41ee-4481-86d4-974a322210b3",
      "name": "Blockchain Web Services",
      "url": "https://www.bws.ninja",
      "email": "[e-mail]",
      "type": "Issuer",
      "verified": true
   }
 ]
}

Delete Issuer

Use this API operation to delete an existing Issuer.

You can only delete issuers with no active Badges!

Only issuers that have not awarded any badge can be deleted.

delete_issuer

POST https://api.bws.ninja/v1/call

Use this operation to delete an issuer.

Request Body

Name	Type	Description

200 Standard 200 response

{
    "statusCode": 200
}

Delete Issuer Parameters

Parameter	Type	Desciption

Delete Issuer API call example

Delete Issuer using Node.js

const axios = require('axios');

/* build request to use BWS Badges solution */
const request = {
{
  "solution": "BWS.Blockchain.Badges",
  "operation": "delete_issuer",
  "parameters":  {
     "issuerId": "https://badges.staging.bws.ninja/certify-badge/issuer/105c00ba-3c18-4d49-938c-566e60d25537"   
  }
}

/* call BWS API using Axios */
let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.bws.ninja/v1/call',
  headers: { 
    'X-Api-Key': 'XqaLg...... A5k2V729v', /* use your API key here! */
    'Content-Type': 'application/json'
  },
  data : JSON.stringify(request)
};

axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Delete Badge Issuer call response

When the API call is successfully executed, you will get an OK status response code.

{
  "statusCode": 200
}

Create a New Badge

A badge is a digital representation of an accomplishment, skill, or authorization that can be earned and displayed. It serves as verifiable proof of a user's achievements and can be shared across digital platforms.

new_badge

POST https://api.bws.ninja/v1/call

Use this operation to create a Badge you can later use to certify recognition.

Request Body

Name	Type	Description

200 Returns the badge ID

{
    "statusCode": 200,
    "info": {
        "id": "https://ipfs.bws.ninja/ipfs/QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN"
    }
}

New Badge Method Parameters

Parameter	Type	Desciption

Your badge image will be saved on the InterPlanetary File System (IPFS) and served from the BWS IPFS gateway service. The images you use should be optimized to be consumed over the internet.

• You must create your badge image to be less than 1 MB in size for fast access (there is a hard limit of 5MB).

• Only the PNG image type is accepted.

Create Badge API call example

Create a new Badge using Node.js

const fs = require('fs');
const axios = require('axios');

/* get the file representing the badge */
const fileData = fs.readFileSync('./files/badge.png');

/* encode file content to base64 */
const encodedData = fileData.toString('base64');

/* build request to use BWS Badges solution */
const request = {
{
  "solution": "BWS.Blockchain.Badges",
  "operation": "new_badge",
  "parameters":  {
     "name": "Cloud Developer",
     "description": "Recognizes professionals who have demonstrated expertise in cloud computing, including development and management of cloud applications and services.",
     "criteria": "To earn this badge, complete an accredited course in cloud computing, demonstrate practical experience with a portfolio of cloud projects, and pass an exam on cloud computing concepts, service models, and development practices.",
     "image": encodedData         
  }
}

/* call BWS API using Axios */
let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.bws.ninja/v1/call',
  headers: { 
    'X-Api-Key': 'XqaLg...... A5k2V729v', /* use your API key here! */
    'Content-Type': 'application/json'
  },
  data : JSON.stringify(request)
};

axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

New Badge call response

When the API call is successfully executed, it returns the badge id, which is also the url you can use to fetch the badge image.

{
  "statusCode": 200,
  "info": {
    "badgeId": "https://badges.staging.bws.ninja/certify-badge/badge/0c4078ab-8195-40fa-9d8d-0389b5547a86"
  }
}

List Badges

Use this operation to get the list of issuer badges.

list_badges

POST https://api.bws.ninja/v1/call

Get the list of issuer badges.

Request Body

Name	Type	Description

200 The list of Badges

{
 "statusCode": 200,
 "info": [
         {
            "@context": "https://w3id.org/openbadges/v2",
            "type": "BadgeClass",
            "id": "https://badges.staging.bws.ninja/certify-badge/badge/a51233aa-f3a9-43ac-b784-a0e72ec93036",
            "name": "BWS Blockchain Developer Associate",
            "description": "Recognizes professionals who have demonstrated expertise in blockchain, including development of applications using BWS cloud services.",
            "image": "https://ipfs.bws.ninja/ipfs/QmXAkiFMsrMYQEiZE76oZ2hT4YEu97bvh8wdCnApvpFdeG",
            "criteria": {
                "narrative": "To earn the Certified Blockchain Professional - BWS Cloud Services badge, candidates must complete an approved training course, demonstrate practical experience with BWS cloud services, submit a project, and pass a comprehensive written and practical exam."
            },
            "issuer": {
                "id": "https://badges.staging.bws.ninja/certify-badge/issuer/d9623c7f-41ee-4481-86d4-974a322210b3",
                "name": "Blockchain Web Services",
                "url": "https://www.bws.ninja",
                "email": "[e-mail]",
                "type": "Issuer",
                "verified": true
            }
        }
 ]
}

List Badges API call example

List Badges using cURL

curl --location 'https://api.staging.bws.ninja/v1/call' \
--header 'X-Api-Key: XqaLg...729v' \
--header 'Content-Type: application/json' \
--data '{
    "solution": "BWS.Blockchain.Badges",
    "operation": "list_badges"
}'

List Badges call response

Once executed correctly, you will get a list of your badges, including the badge ID and the badge data.

{
 "statusCode": 200,
 "info": [
    {
        "@context": "https://w3id.org/openbadges/v2",
        "type": "BadgeClass",
        "id": "https://badges.staging.bws.ninja/certify-badge/badge/a51233aa-f3a9-43ac-b784-a0e72ec93036",
        "name": "BWS Blockchain Developer Associate",
        "description": "Recognizes professionals who have demonstrated expertise in blockchain, including development of applications using BWS cloud services.",
        "image": "https://ipfs.bws.ninja/ipfs/QmXAkiFMsrMYQEiZE76oZ2hT4YEu97bvh8wdCnApvpFdeG",
        "criteria": {
            "narrative": "To earn the Certified Blockchain Professional - BWS Cloud Services badge, candidates must complete an approved training course, demonstrate practical experience with BWS cloud services, submit a project, and pass a comprehensive written and practical exam."
        },
        "issuer": {
            "id": "https://badges.staging.bws.ninja/certify-badge/issuer/d9623c7f-41ee-4481-86d4-974a322210b3",
            "name": "Blockchain Web Services",
            "url": "https://www.bws.ninja",
            "email": "[e-mail]",
            "type": "Issuer",
            "verified": true
        }
    }
 ]
}

Delete Badge

Use this API operation to delete an existing Badge.

You can only delete badges with no active Awards!

Once a certificate has been awarded to an individual (recipient), the related badge can not be deleted.

delete_badge

POST https://api.bws.ninja/v1/call

Use this operation to delete a badge.

Request Body

Name	Type	Description

200 Standard 200 response

{
    "statusCode": 200
}

Delete Badge Parameters

Parameter	Type	Desciption

Delete Badge API call example

Delete a Badge using Node.js

const axios = require('axios');

/* build request to use BWS Badges solution */
const request = {
{
  "solution": "BWS.Blockchain.Badges",
  "operation": "delete_badge",
  "parameters":  {
     "badgeId": "https://badges.staging.bws.ninja/certify-badge/badge/0c4078ab-8195-40fa-9d8d-0389b5547a86"   
  }
}

/* call BWS API using Axios */
let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.bws.ninja/v1/call',
  headers: { 
    'X-Api-Key': 'XqaLg...... A5k2V729v', /* use your API key here! */
    'Content-Type': 'application/json'
  },
  data : JSON.stringify(request)
};

axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Delete Badge call response

If the call succeeds and the badge gets deleted, you will get a standard 200 response.

{
  "statusCode": 200
}

Award a Badge

Awarding a badge represents the digital acknowledgment of an individual's skills or achievements.

It enables the conferring of verifiable digital credentials to individuals who meet specific criteria, providing a modern way to recognize professional development, accomplishments, or learning milestones.

new_award

POST https://api.bws.ninja/v1/call

Use this operation to award a badge to an individual (recipient).

Request Body

Name	Type	Description

200 Returns the award ID

{
    "statusCode": 200,
    "info": {
        "awardId": "https://badges.staging.bws.ninja/certify-badge/award/23d09456-b660-4624-ab32-a71dc29cd40c"
    }
}

Award Badge Parameters

Parameter	Type	Desciption

Recipient Parameters JSON

Include the below parameters to identify the certificate (award) recipient.

Recipient email data encryption.

When you send the recipient's email, we hash (encrypt) the original, and the readable email address is never saved into our databases.

Parameter	Type	Desciption

Award a Badge API call example

Award a Badge using Node.js

const axios = require('axios');

/* build request to use BWS Badges solution */
const request = {
    "solution": "BWS.Blockchain.Badges",
    "operation": "new_award",
    "parameters":  {
         "badgeId": "https://badges.staging.bws.ninja/certify-badge/badge/0c4078ab-8195-40fa-9d8d-0389b5547a86",
         "issuedOn": 1707123790310,
         "recipient": {
            "email": "[e-mail]",
            "name": "Wile Ethelbert Coyote"
         }         
    }
}

/* call BWS API using Axios */
let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.bws.ninja/v1/call',
  headers: { 
    'X-Api-Key': 'XqaLg...... A5k2V729v', /* use your API key here! */
    'Content-Type': 'application/json'
  },
  data : JSON.stringify(request)
};

axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Award a Badge call response

If everything goes ok, you get the awardId, which is also the URL to access the Open Badge award definition.

{
    "statusCode": 200,
    "info": {
        "awardId": "https://badges.staging.bws.ninja/certify-badge/award/d7da7231-548e-4fc3-b5a9-b0ef2f34e9a8"
    }
}

List Awards

Use this operation to get the list of awards for ALL the issuers you have registered.

list_awards

POST https://api.bws.ninja/v1/call

Get the full list of awards.

Request Body

Name	Type	Description

200 The list of awards

{
 "statusCode": 200,
 "info": [
     {
        "@context": "https://w3id.org/openbadges/v2",
        "type": "Assertion",
        "id": "https://badges.staging.bws.ninja/certify-badge/award/db06f3e5-43c8-447f-bc82-232df1f3be62",
        "recipient": {
            "type": "email",
            "hashed": true,
            "salt": "0f02bc8522",
            "identity": "sha256$c7009cc9daf7971c763734a217eadd14572f16cbb397cd61242621459822cbb2",
            "name": "Nacho Coll"
        },
        "badge": {
            "type": "BadgeClass",
            "id": "https://badges.staging.bws.ninja/certify-badge/badge/0c4078ab-8195-40fa-9d8d-0389b5547a86",
            "name": "Blockchain Web Services Developer Associate",
            "description": "Recognizes professionals who have demonstrated expertise in blockchain, including development and management of blockchain applications and services using Blockchain Web Services API.",
            "image": "https://ipfs.bws.ninja/ipfs/QmXAkiFMsrMYQEiZE76oZ2hT4YEu97bvh8wdCnApvpFdeG",
            "criteria": {
                "narrative": "To earn this badge, complete an accredited course in blockchain, demonstrate practical experience with a portfolio of Blockchain Web Services solutions, and pass an exam on blockchain computing concepts, service models, and development practices."
                 },
            "issuer": {
                "id": "https://badges.staging.bws.ninja/certify-badge/issuer/a68d1d72-1365-4114-8349-0b2e220f43e3",
                "name": "Blockchain Web Services",
                "url": "https://www.bws.ninja",
                "email": "[e-mail]",
                "type": "Issuer"
            }
        },
        "verification": {
            "type": "HostedBadge"
        },
        "issuedOn": "2024-01-17T17:55:31.903Z"
    }
 ]
}

List Awards API call example

List Awards using cURL

curl --location 'https://api.staging.bws.ninja/v1/call' \
--header 'X-Api-Key: XqaLg...729v' \
--header 'Content-Type: application/json' \
--data '{
    "solution": "BWS.Blockchain.Badges",
    "operation": "list_awards"
}'

List Awards call Response

Once executed correctly, you will get a list of your account badge awards.

{
 "statusCode": 200,
 "info": [
    {
        "@context": "https://w3id.org/openbadges/v2",
        "type": "Assertion",
        "id": "https://badges.staging.bws.ninja/certify-badge/award/db06f3e5-43c8-447f-bc82-232df1f3be62",
        "recipient": {
            "type": "email",
            "hashed": true,
            "salt": "0f02bc8522",
            "identity": "sha256$c7009cc9daf7971c763734a217eadd14572f16cbb397cd61242621459822cbb2",
            "name": "Nacho Coll"
        },
        "badge": {
            "type": "BadgeClass",
            "id": "https://badges.staging.bws.ninja/certify-badge/badge/0c4078ab-8195-40fa-9d8d-0389b5547a86",
            "name": "Blockchain Web Services Developer Associate",
            "description": "Recognizes professionals who have demonstrated expertise in blockchain, including development and management of blockchain applications and services using Blockchain Web Services API.",
            "image": "https://ipfs.bws.ninja/ipfs/QmXAkiFMsrMYQEiZE76oZ2hT4YEu97bvh8wdCnApvpFdeG",
            "criteria": {
                "narrative": "To earn this badge, complete an accredited course in blockchain, demonstrate practical experience with a portfolio of Blockchain Web Services solutions, and pass an exam on blockchain computing concepts, service models, and development practices."
                 },
            "issuer": {
                "id": "https://badges.staging.bws.ninja/certify-badge/issuer/a68d1d72-1365-4114-8349-0b2e220f43e3",
                "name": "Blockchain Web Services",
                "url": "https://www.bws.ninja",
                "email": "[e-mail]",
                "type": "Issuer"
            }
        },
        "verification": {
            "type": "HostedBadge"
        },
        "issuedOn": "2024-01-17T17:55:31.903Z"
    }
 ]
}

Send Award Email

Use this operation if you want BWS to email an award recipient, including a link to download, share, and visualize his achieved award.

Certificate Recipient Email

send_award_email

POST https://api.bws.ninja/v1/call

Send the award recipient a congratulatory email indicating how to download and share the acquired certification.

Request Body

Name	Type	Description

200 Standard 200 response

{
 "statusCode": 200
}

Send Award Email parameters

Parameter	Type	Desciption

Send Award API call example

You need to know the award recipient's email address!

In full compliance with the General Data Protection Regulation (GDPR), our API is designed to be strongly committed to privacy and data protection. We understand the importance of safeguarding personal information and uphold the highest data privacy standards.

When our API processes email data, it does so in real time. The data is transmitted securely and never recorded, stored, or saved on our servers.

Send Award Email using cURL

curl --location 'https://api.staging.bws.ninja/v1/call' \
--header 'X-Api-Key: XqaLg...729v' \
--header 'Content-Type: application/json' \
--data '{
    "solution": "BWS.Blockchain.Badges",
    "operation": "send_award_email",
    "parameters": {
        "badgeId": "https://badges.staging.bws.ninja/certify-badge/award/23d09456-b660-4624-ab32-a71dc29cd40c",
        "email": "[e-mail]"
}'

Send Award Email call response

You will get a standard 200 response if the email is correctly sent.

{
 "statusCode": 200
}