Issuers

An Issuer represents an entity or organization responsible for defining, creating, and awarding digital badges to acknowledge and verify individual achievements, skills, or competencies.

new_issuer

Use this API operation to set up a new Issuer, enabling them to design and issue digital badges and manage awards efficiently. This operation is the first step in establishing a trusted source for verifiable credentials within your platform.

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

Request Body

Name	Type	Description
solution*	string	BWS.Blockchain.Badges
operation*	string	new_issuer
parameters*	JSON	check method parameters

new_issuer Method Parameters

WARNING

Use an email address you have access to!

To confirm your authorization to use the provided email, we will send a verification message to it (How to Verify a Badge Issuer).

Parameter	Type	Desciption
name	string	Issuer Name (e.g. "Blockchain Academy")
url	string	Issuer website URL
email	string	The issuer contact email address.

new_issuer API Call Example

new_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": "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);
  });

new_issuer Call Response

When the API call is successfully executed, it returns the issuerId, which also serves as the URL to retrieve the Issuer's Open Badge v2.0 JSON.

This JSON file contains metadata about the Badge Issuer, including essential information such as the organization's name, description, and verification details, formatted according to the Open Badge standard for interoperability and trust.

{
  "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_issuer API call to verify the issuer).

WARNING

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.

verify_issuer

To legitimate badge issuers, we send a verification link and code to the address you use when calling new_issuer API call operation.

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

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

Request Body

Name	Type	Description
solution*	string	BWS.Blockchain.Badges
operation*	string	verify_issuer
parameters*	JSON	check method parameters

200 Standard 200 response

{
    "statusCode": 200
}

verify_issuer Method Parameters

Parameter	Type	Desciption
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

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

Get the list of the issuers you created.

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

Request Body

Name	Type	Description
solution*	string	BWS.Blockchain.Badges
operation*	string	list_issuers

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

delete_issuer

Use this API operation to delete an existing Issuer.

INFO

You can only delete issuers with no active Badges!

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

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

Request Body

Name	Type	Description
solution*	string	BWS.Blockchain.Badges
operation*	string	delete_issuer
parameters*	JSON	check method parameters

delete_issuer Method Parameters

Parameter	Type	Desciption
issuerId	string	The issuer ID you received when adding a new badge issuer.

delete_issuer API Call Example

Delete an 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_issuer Call Response

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

{
  "statusCode": 200
}