Contact Us Create Account Sign In

Credentials 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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

new_issuer

parameters*

JSON

check Method Parameters

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

ParameterTypeDesciption

name

string

Issuer Name (e.g. "Blockchain Academy")

url

string

Issuer website URL

email

string

The issuer contact email address.

Add Issuer API call example

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": "contact@mycloudacademywebsiteurl.com"      
  }
}

/* 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.

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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

verify_issuer

parameters*

JSON

check Method Parameters

{
    "statusCode": 200
}

Verify Issuer Parameters

ParameterTypeDesciption

issuerId

string

The issuer ID you received when adding a new badge issuer.

code

string

The code you received by email.

Verify Issuer API call example

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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

list_issuers

{
 "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": "info@bws.ninja"     
   }
 ]
}

List Issuers API call example

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": "badges@bws.ninja",
      "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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

delete_issuer

parameters*

JSON

check Method Parameters

{
    "statusCode": 200
}

Delete Issuer Parameters

ParameterTypeDesciption

issuerId

string

The issuer ID you received when adding a new badge issuer.

Delete Issuer API call example

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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

new_badge

parameters*

JSON

check Method Parameters

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

New Badge Method Parameters

ParameterTypeDesciption

issuerId

string

The badge issuer ID (check Add Badge Issuer)

name

string

Badge name (e.g. "Certified Data Analyst").

description

string

A description of the badge and what it represents.

criteria

string

Narrative describing the criteria to earn the badge.

image

base64

The image representing the badge as a base64 encoded string.

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

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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

list_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": "badges@bws.ninja",
                "type": "Issuer",
                "verified": true
            }
        }
 ]
}

List Badges API call example

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": "badges@bws.ninja",
            "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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

delete_badge

parameters*

JSON

check Method Parameters

{
    "statusCode": 200
}

Delete Badge Parameters

ParameterTypeDesciption

badgeId

string

The badge ID you received when adding a new badge and want to delete.

Delete Badge API call example

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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

new_award

parameters*

JSON

check Method Parameters

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

Award Badge Parameters

ParameterTypeDesciption

badgeId

string

The badge ID (check Create a new Badge on how to create a Badge and get its ID).

issuedOn

long

Unix time in milliseconds representing the date the award was issued.

expires optional

long

Unix time in milliseconds representing the date the award will expire.

recipient

JSON

The Recipient Parameters representing the awarded identity.

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.

ParameterTypeDesciption

email

string

The recipient email address.

name

string

The full name of the recipient.

Award a Badge API call example

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": "wile@coyote.com",
            "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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

list_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": "info@bws.ninja",
                "type": "Issuer"
            }
        },
        "verification": {
            "type": "HostedBadge"
        },
        "issuedOn": "2024-01-17T17:55:31.903Z"
    }
 ]
}

List Awards API call example

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": "info@bws.ninja",
                "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.

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

NameTypeDescription

solution*

string

BWS.Blockchain.Badges

operation*

string

send_award

parameters

JSON

check Method Parameters

{
 "statusCode": 200
}

Send Award Email parameters

ParameterTypeDesciption

awardId

string

The award ID (check Award a Badge on how to create a new award).

email

string

The award recipient's email address

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.

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": "nacho.coll@bws.ninja"
}'

Send Award Email call response

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

{
 "statusCode": 200
}

PreviousCredentials DashboardNextBWS.NFT.zK

Last updated