IOTA Certification API v1.0.11

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

To gain access to the certification API you must first contact IOTA Foundation to receive an organizationId.

You will receive two ids, one for the Development environment and one for the Production environment.

We will also create you an administration user for each environment.

Structure

An organization has administrators who can perform operations on backgrounds, templates and issuers.

Issuers can perform certificate and blacklist operations.

Endpoints

The endpoints for the two environments Development and Production are as follows:

Base URLs:

• https://certification-api.iota.works/

• https://certification-api.iota.org/

Version

Version information about the API

getVersion

Code samples

GET https://certification-api.iota.works/ HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X GET https://certification-api.iota.works/ \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://certification-api.iota.works/", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /

Get the API details

Example responses

200 Response

{
  "name": "iota-certification-api",
  "version": "1.0.10"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» name	string	true	none	The name of the API
» version	string	true	none	The current version of the API

checkVersion

Code samples

POST https://certification-api.iota.works/ HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://certification-api.iota.works/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "checkVersion": "1.0.9"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://certification-api.iota.works/", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /

Check the API for a new version

Body parameter

{
  "checkVersion": "1.0.9"
}

Parameters

Name	In	Type	Required	Description
checkVersion	body	string	true	A version that is compared to the current version of the API

Example responses

200 Response

{
  "version": "1.0.10",
  "updateAvailable": true
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» version	string	true	none	The current version of the API
» updateAvailable	boolean	true	none	True if the checkVersion is older than the current one

Backgrounds

A background is the base layer of the page that the content for the certificate is generated on top of, it is created from svg markup. The content can be whatever you like but must contain markers to include certificate information. You can have multiple backgrounds for use with different templates.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 842 596" version="1.1" xmlns="http://www.w3.org/2000/svg">
    <style>
    .caption {
        font-family: "Nunito Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
        font-weight: 300;
        font-size: 26px;
    }
    .training-title {
        font-family: "Nunito Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
        font-weight: 600;
        font-size: 32px;
    }
    .participant {
        font-family: "Nunito Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
        font-weight: 600;
        font-size: 25px;
    }
    .participation-date {
        font-family: "Nunito Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
        font-weight: normal;
        font-size: 18px;
    }
    .info {
        font-family: "Nunito Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
        font-weight: 300;
        font-size: 10px;
    }
    .hash {
        font-family: "Nunito Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
        font-weight: normal;
        font-size: 8px;
    }
    </style>
    <rect x="0" y="0" width="842" height="596" style="fill:white;"/>
    <rect x="30.81" y="30.82" width="779.66" height="533.38" style="fill:none;stroke:rgb(189,190,192);stroke-width:12px;"/>
    <text x="100" y="100">Additional content</text>
    <text x="100" y="480" style="font-family:'FreestyleScript-Regular', 'Freestyle Script', cursive;font-size:33.333px;">My Signature</text>
    <text x="50%" y="165" class="caption" text-anchor="middle">Certificate Of Attendance</text>
    <text x="50%" y="220" class="training-title" text-anchor="middle">%%TRAINING-TITLE%%</text>
    <text x="50%" y="295" class="participant" text-anchor="middle">%%PARTICIPANT%%</text>
    <text x="50%" y="352" class="participation-date" text-anchor="middle">%%PARTICIPATION-DATE%%</text>
    <text x="50%" y="390" class="info" text-anchor="middle">This certificate confirms that the training specified was attended and completed by the person on the date shown.</text>
    <text x="50%" y="410" class="info" text-anchor="middle">You can validate the authenticity of this certificate by scanning the QR code, or by visiting %%AUTH-DOMAIN%%</text>
    <text x="50%" y="420" class="info" text-anchor="middle">and entering the hash shown at the bottom of this certificate.</text>
    <text x="17%" y="545" class="hash" text-anchor="start">Hash: %%HASH%%</text>
    <text x="83%" y="545" class="hash" text-anchor="end">Issued On: %%ISSUED-DATE%%</text>
    %%TEMPLATE-ADDITIONAL%%
    %%ISSUER-SIGNATURE%%
    <svg x="44%" y="430">%%QR-CODE%%</svg>
</svg>

When an issuer generates a certificate they supply the following additional information trainingTitle, participant, participationDate, issuedDate. These fields along with with other information about the generated certificate is substituted in to the placeholders.

The example shows a simple background with a border and markers for the content.

The fields for a background are shown in the table below, they are all optional.

Marker	Content	Example
%%TEMPLATE-ADDITIONAL%%	Template additional content	The additional content svg from the template
%%ISSUER-SIGNATURE%%	Issuer Signature	The additional signature svg from the issuer
%%CAPTION%%	Caption	Certificate of Attendance
%%TRAINING-TITLE%%	Training Title	Training Course
%%PARTICIPANT%%	Participant	Fred Bloggs
%%PARTICIPATION-DATE-DATE%%	Participation Date	01/01/2019
%%ISSUED-DATE%%	Issued Date	01/01/2019
%%HASH%%	Hash	Hash: AAA....ZZZZ
%%AUTH-DOMAIN%%	Authenticate Domain	https://certification.iota.org
%%QR-CODE%%	QR Code	Data in QR code is a url that points to https://certification.iota.org/AAA....ZZZZ

A complete template using all the markers can be found in ./background.svg

createUpdateBackground

Code samples

PUT https://certification-api.iota.works/background HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PUT https://certification-api.iota.works/background \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "backgroundId": "BACKGROUNDID",
  "content": "<text>abc</text>"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/background',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://certification-api.iota.works/background", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /background

Create or update a background, if you don't provide a backgroundId a new background will be created.

Body parameter

{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "backgroundId": "BACKGROUNDID",
  "content": "<text>abc</text>"
}

Parameters

Name	In	Type	Required	Description
adminId	body	string	true	The id of an administrator
adminPassPhrase	body	string	true	The passphrase of the administrator
backgroundId	body	string	false	The id to use for the background if updating
content	body	string	true	The SVG content for the background

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "backgroundId": "BACKGROUNDID"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» backgroundId	string	true	none	The id of the background that was created/updated

getBackground

Code samples

POST https://certification-api.iota.works/background HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://certification-api.iota.works/background \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "backgroundId": "BACKGROUNDID"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/background',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://certification-api.iota.works/background", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /background

Get a background.

Body parameter

{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "backgroundId": "BACKGROUNDID"
}

Parameters

Name	In	Type	Required	Description
adminId	body	string	true	The id of an administrator
adminPassPhrase	body	string	true	The passphrase of the administrator
backgroundId	body	string	true	The id of the background to get

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "content": "<text>abc</text>"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» content	string	true	none	The svg content of the background

deleteBackground

Code samples

DELETE https://certification-api.iota.works/background?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&backgroundId=BACKGROUNDID HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X DELETE https://certification-api.iota.works/background?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&backgroundId=BACKGROUNDID \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/background?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&backgroundId=BACKGROUNDID',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://certification-api.iota.works/background", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /background

Delete a background.

Parameters

Name	In	Type	Required	Description
adminId	query	string	true	The id of an administrator
adminPassPhrase	query	string	true	The passphrase of the administrator
backgroundId	query	string	true	The id of the background to delete

Example responses

200 Response

{
  "success": true,
  "message": "OK"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation

listBackgrounds

Code samples

GET https://certification-api.iota.works/backgrounds/{organizationId} HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X GET https://certification-api.iota.works/backgrounds/{organizationId} \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/backgrounds/{organizationId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://certification-api.iota.works/backgrounds/{organizationId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /backgrounds/{organizationId}

Get a list of all the backgrounds for your organization.

Parameters

Name	In	Type	Required	Description
organizationId	path	string	true	The id allocated to your organization by IF

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "backgrounds": [
    "BACKGROUNDID",
    "ANOTHERBACKGROUNDID"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» backgrounds	[string]	true	none	The ids of the backgrounds

Templates

A template is the next layer up on the certificate design. You can specify a caption which will be substituted into the %%CAPTION%% marker.

You can also specify any additional content in the form of svg markup.

In addition you can specify the color that the QR code will appear on the certificate.

createUpdateTemplate

Code samples

PUT https://certification-api.iota.works/template HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PUT https://certification-api.iota.works/template \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "templateId": "TEMPLATEID",
  "name": "My Template",
  "backgroundId": "BACKGROUNDID",
  "additionalContent": "<text>Additional content</text>",
  "caption": "Developer Certificate",
  "qrColor": "#000000",
  "canIssue": "true"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/template',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://certification-api.iota.works/template", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /template

Create or update a template.

Body parameter

{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "templateId": "TEMPLATEID",
  "name": "My Template",
  "backgroundId": "BACKGROUNDID",
  "additionalContent": "<text>Additional content</text>",
  "caption": "Developer Certificate",
  "qrColor": "#000000",
  "canIssue": "true"
}

Parameters

Name	In	Type	Required	Description
adminId	body	string	true	The id of an administrator
adminPassPhrase	body	string	true	The passphrase of the administrator
templateId	body	string	false	The id to use for the template if updating
name	body	string	true	A friendly name to use for the template
backgroundId	body	string	true	The id of the background the template will be combined with
additionalContent	body	string	true	Any additional svg markup for the template
caption	body	string	true	The caption to be substituted into the %%CAPTION%% field on the background
qrColor	body	string	true	A hex color to be used for the QR code
canIssue	body	boolean	true	Set to true to allow this certificate template to be issued

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "templateId": "TEMPLATEID"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» templateId	string	true	none	The id of the template that was created/updated

getTemplate

Code samples

POST https://certification-api.iota.works/template HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://certification-api.iota.works/template \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "templateId": "TEMPLATEID"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/template',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://certification-api.iota.works/template", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /template

Get a template.

Body parameter

{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "templateId": "TEMPLATEID"
}

Parameters

Name	In	Type	Required	Description
adminId	body	string	true	The id of an administrator
adminPassPhrase	body	string	true	The passphrase of the administrator
templateId	body	string	true	The id of the template to get

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "name": "My Template",
  "backgroundId": "BACKGROUNDID",
  "additionalContent": "<text>Additional content</text>",
  "caption": "Developer Certificate",
  "qrColor": "#000000",
  "canIssue": true
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» name	string	true	none	A friendly name to use for the template
» backgroundId	string	true	none	The id of the background the template will be combined with
» additionalContent	string	true	none	Any additional svg markup for the template
» caption	string	true	none	The caption to be substituted into the %%CAPTION%% field on the background
» qrColor	string	true	none	A hex color to be used for the QR code
» canIssue	boolean	true	none	Set to true to allow this certificate template to be issued

deleteTemplate

Code samples

DELETE https://certification-api.iota.works/template?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&templateId=TEMPLATEID HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X DELETE https://certification-api.iota.works/template?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&templateId=TEMPLATEID \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/template?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&templateId=TEMPLATEID',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://certification-api.iota.works/template", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /template

Delete a template.

Parameters

Name	In	Type	Required	Description
adminId	query	string	true	The id of an administrator
adminPassPhrase	query	string	true	The passphrase of the administrator
templateId	query	string	true	The id of the template to delete

Example responses

200 Response

{
  "success": true,
  "message": "OK"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation

listTemplates

Code samples

GET https://certification-api.iota.works/templates/{organizationId} HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X GET https://certification-api.iota.works/templates/{organizationId} \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/templates/{organizationId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://certification-api.iota.works/templates/{organizationId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /templates/{organizationId}

Get a list of all the templates for your organization.

Parameters

Name	In	Type	Required	Description
organizationId	path	string	true	The id allocated to your organization by IF

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "templates": [
    {
      "id": "TEMPLATEID",
      "name": "My Template"
    },
    {
      "id": "TEMPLATEID2",
      "name": "Another Template"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» templates	[object]	true	none	The ids and names of the templates
»» id	string	false	none	The id of the template
»» name	string	false	none	The name of the template

Issuers

Issuers are the users who can create certificates (administators are also issuers). Each issuer can have their own signature data, it is additional svg content that is combined with the template. An issuer has a pass phrase used to generate their certificates.

An issuer is able to issue certificates based on different templates, but the same content will always get combined.

createUpdateIssuer

Code samples

PUT https://certification-api.iota.works/issuer HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PUT https://certification-api.iota.works/issuer \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "name": "Fred Bloggs",
  "oldPassPhrase": "oldpass",
  "newPassPhrase": "P4ssw0rd",
  "canIssue": "True",
  "allowedTemplates": [
    "TEMPLATE1",
    "TEMPLATE2"
  ],
  "signature": "<text>Fred Bloggs</text>",
  "isAdministrator": "false"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/issuer',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://certification-api.iota.works/issuer", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /issuer

Create or update a issuer.

Body parameter

{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "name": "Fred Bloggs",
  "oldPassPhrase": "oldpass",
  "newPassPhrase": "P4ssw0rd",
  "canIssue": "True",
  "allowedTemplates": [
    "TEMPLATE1",
    "TEMPLATE2"
  ],
  "signature": "<text>Fred Bloggs</text>",
  "isAdministrator": "false"
}

Parameters

Name	In	Type	Required	Description
adminId	body	string	true	The id of an administrator
adminPassPhrase	body	string	true	The passphrase of the administrator
name	body	string	false	The name of the issuer
oldPassPhrase	body	string	false	This field should be set if you want to change the password for an existing issuer
newPassPhrase	body	string	false	Pass phrase for the issuer to generate certificates
canIssue	body	boolean	false	Can the issuer currently issue certificates
allowedTemplates	body	[string]	false	List of templates the issuer is allowed to issue
signature	body	string	false	Additional svg content to add to certificates for the issuer
isAdministrator	body	boolean	false	Is the issuer also an administrator

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "issuerId": "ISSUERID"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» issuerId	string	false	none	The id of the issuer that was created/updated

getIssuer

Code samples

POST https://certification-api.iota.works/issuer HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://certification-api.iota.works/issuer \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "issuerId": "ISSUERID"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/issuer',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://certification-api.iota.works/issuer", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /issuer

Get an issuer.

Body parameter

{
  "adminId": "AAAAAAAAAAAA",
  "adminPassPhrase": "P4ssw0rd",
  "issuerId": "ISSUERID"
}

Parameters

Name	In	Type	Required	Description
adminId	body	string	true	The id of an administrator
adminPassPhrase	body	string	true	The passphrase of the administrator
issuerId	body	string	true	The id of the issuer to get

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "name": "Fred Bloggs",
  "canIssuer": true,
  "allowedTemplates": [
    "TEMPLATE1",
    "TEMPLATE2"
  ],
  "signature": "<text>Fred Bloggs</text>",
  "isAdministrator": false
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» name	string	true	none	Name of the issuer
» canIssuer	boolean	false	none	Can the issuer currently issue certificates
» allowedTemplates	[string]	true	none	List of templates the issuer is allowed to issue
» signature	string	true	none	Additional svg content to add to certificates for the issuer
» isAdministrator	boolean	true	none	Is the issuer also an administrator

deleteIssuer

Code samples

DELETE https://certification-api.iota.works/issuer?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&issuerId=ISSUERID HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X DELETE https://certification-api.iota.works/issuer?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&issuerId=ISSUERID \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/issuer?adminId=AAAAAAAAAAAA&adminPassPhrase=P4ssw0rd&issuerId=ISSUERID',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://certification-api.iota.works/issuer", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /issuer

Delete an issuer.

Parameters

Name	In	Type	Required	Description
adminId	query	string	true	The id of an administrator
adminPassPhrase	query	string	true	The passphrase of the administrator
issuerId	query	string	true	The id of the issuer to delete

Example responses

200 Response

{
  "success": true,
  "message": "OK"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation

listIssuers

Code samples

GET https://certification-api.iota.works/issuers/{organizationId} HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X GET https://certification-api.iota.works/issuers/{organizationId} \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/issuers/{organizationId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://certification-api.iota.works/issuers/{organizationId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /issuers/{organizationId}

Get a list of all the issuers for your organization.

Parameters

Name	In	Type	Required	Description
organizationId	path	string	true	The id allocated to your organization by IF

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "issuers": [
    {
      "id": "ISSUERID",
      "name": "Fred Bloggs"
    },
    {
      "id": "ISSUERID2",
      "name": "John Smith"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» issuers	[object]	true	none	The ids and names of the issuers
»» id	string	false	none	The id of the issuer
»» name	string	false	none	The name of the issuer

Certificates

Create, authenticate and view certificates. There are also operations to blacklist certificates.

createCertificate

Code samples

PUT https://certification-api.iota.works/certificate HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PUT https://certification-api.iota.works/certificate \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd",
  "templateId": "TEMPLATEID",
  "trainingTitle": "Developer Certification",
  "participant": "Joan Jet",
  "participationDate": "2019/08/14 - 2020/08/13",
  "issuedDate": "2019/08/14"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/certificate',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://certification-api.iota.works/certificate", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /certificate

Create a certificate.

Body parameter

{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd",
  "templateId": "TEMPLATEID",
  "trainingTitle": "Developer Certification",
  "participant": "Joan Jet",
  "participationDate": "2019/08/14 - 2020/08/13",
  "issuedDate": "2019/08/14"
}

Parameters

Name	In	Type	Required	Description
issuerId	body	string	true	The id of the issuer
issuerPassPhrase	body	string	true	The pass phrase for the issuer
templateId	body	string	true	Which template are we issuing the certificate with. Since v1.0.10 this is used instead of template for consistency
trainingTitle	body	string	true	What was the training for
participant	body	string	true	The name of the participant
participationDate	body	string	true	The date of participation, this is plain text so can be a range
issuedDate	body	string	true	The date the certificate was issued

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "hash": "999999999999999999999999999999999999999999999999999999999999999999999999999999999",
  "validationUrl": "https://certification.iota.works/999999999999999999999999999999999999999999999999999999999999999999999999999999999",
  "version": 1
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» hash	string	true	none	The hash of the certificate on the tangle that was generated
» validationUrl	string	true	none	A url you can open in a browser to show validation results
» version	number	true	none	The version of the certificate payload

authenticateCertificate

Code samples

GET https://certification-api.iota.works/authenticate/{hash} HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X GET https://certification-api.iota.works/authenticate/{hash} \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/authenticate/{hash}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://certification-api.iota.works/authenticate/{hash}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /authenticate/{hash}

Authenticate the certificate from the hash. If the certificate is not authentic success will be false and the message field will be populated in the response.

Parameters

Name	In	Type	Required	Description
hash	path	string	true	The hash of the certificate to validate

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "issuerId": "ISSUERID",
  "issuerName": "Fred Bloggs",
  "templateId": "TEMPLATEID",
  "issuedDate": "2019/08/14",
  "trainingTitle": "Developer Certification",
  "participant": "Joan Jet",
  "participationDate": "2019/08/14 - 2020/08/13",
  "version": 1
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» issuerId	string	true	none	Who issued the certificate
» issuerName	string	true	none	Who issued the certificate
» templateId	string	true	none	What template was used for the certificate
» issuedDate	string	true	none	When was the certificate issued
» trainingTitle	string	true	none	What the certificate was issued for
» participant	string	true	none	The name the certificate was issued for
» participationDate	string	true	none	The date the certificate was issued
» version	number	true	none	The version of the certificate format

viewCertificate

Code samples

GET https://certification-api.iota.works/certificate/{hash} HTTP/1.1
Host: certification-api.iota.works
Accept: image/svg+xml

# You can also use wget
curl -X GET https://certification-api.iota.works/certificate/{hash} \
  -H 'Accept: image/svg+xml'

const fetch = require('node-fetch');

const headers = {
  'Accept':'image/svg+xml'

};

fetch('https://certification-api.iota.works/certificate/{hash}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"image/svg+xml"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://certification-api.iota.works/certificate/{hash}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /certificate/{hash}

View the certificate if it is valid.

Parameters

Name	In	Type	Required	Description
hash	path	string	true	The hash of the certificate to view
contentType	query	string	false	The contentType can be image/svg+xml or application/pdf
filename	query	string	false	If you specify a filename the Content-Disposition: attachment header will be set prompting a browser to download the file.

Example responses

200 Response

Responses

Status	Meaning	Description	Schema
200	OK	Successful	string

listIssued

Code samples

POST https://certification-api.iota.works/issued/{organizationId} HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://certification-api.iota.works/issued/{organizationId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/issued/{organizationId}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://certification-api.iota.works/issued/{organizationId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /issued/{organizationId}

Get a list of issued certificate for the specified issuer. The results will be paged based on the parameters supplied.

Body parameter

{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd"
}

Parameters

Name	In	Type	Required	Description
organizationId	path	string	true	The id allocated to your organization by IF
page	query	number	false	The page parameter is indexed from 0, if not supplied it will return page 0.
pageSize	query	number	false	If no pageSize is supplied it will default to 10. The return data will include a pageSize, if the requested size was not available it will return a different value, you should then use this value in further requests.
issuerId	body	string	true	Who issued the certificates
issuerPassPhrase	body	string	true	The pass phrase for the issuer

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "items": [
    {
      "templateId": "TEMPLATEID",
      "issuedDate": "2019/08/14",
      "trainingTitle": "Developer Certification",
      "participant": "Joan Jet",
      "participationDate": "2019/08/14 - 2020/08/13",
      "hash": "999999999999999999999999999999999999999999999999999999999999999999999999999999999",
      "version": 1
    }
  ],
  "totalPages": 1,
  "totalItems": 1,
  "pageSize": 15
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» items	[object]	false	none	The list of issued certificates
»» templateId	string	false	none	What template was used for the certificate
»» issuedDate	string	false	none	When was the certificate issued
»» trainingTitle	string	false	none	What the certificate was issued for
»» participant	string	false	none	The name the certificate was issued for
»» participationDate	string	false	none	The date the certificate was issued
»» hash	string	false	none	The hash of the certificate
»» version	number	false	none	The version format for the data. 0 - hash is bundle hash, 1 - hash in transaction hash
» totalPages	number	false	none	The total number of pages
» totalItems	number	false	none	The total number of items
» pageSize	number	false	none	The page size used for the items

blacklistOptions

Code samples

GET https://certification-api.iota.works/blacklist-options HTTP/1.1
Host: certification-api.iota.works
Accept: application/json

# You can also use wget
curl -X GET https://certification-api.iota.works/blacklist-options \
  -H 'Accept: application/json'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/blacklist-options',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://certification-api.iota.works/blacklist-options", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /blacklist-options

Get a list of all the black list options which can be used in black list operations.

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "options": [
    {
      "name": "Not Blacklisted",
      "value": 0
    },
    {
      "name": "Blacklisted",
      "value": 1
    },
    {
      "name": "Expired",
      "value": 2
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» options	[object]	true	none	The ids and names of the options
»» id	string	false	none	The id of the option
»» name	string	false	none	The name of the option

setBlacklist

Code samples

PUT https://certification-api.iota.works/blacklist HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PUT https://certification-api.iota.works/blacklist \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd",
  "hash": "999999999999999999999999999999999999999999999999999999999999999999999999999999999",
  "reason": 1,
  "details": "Issued with incorrect details"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/blacklist',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://certification-api.iota.works/blacklist", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /blacklist

Set the blacklist for a certificate.

Body parameter

{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd",
  "hash": "999999999999999999999999999999999999999999999999999999999999999999999999999999999",
  "reason": 1,
  "details": "Issued with incorrect details"
}

Parameters

Name	In	Type	Required	Description
issuerId	body	string	true	Who issued the certificates
issuerPassPhrase	body	string	true	The pass phrase for the issuer
hash	body	string	true	The hash of the certificate to blacklist
reason	body	number	true	The reason the certificate is blacklisted, a value from the options
details	body	string	true	A more detailed description of why the certificate was blacklisted

Example responses

200 Response

{
  "success": true,
  "message": "OK"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation

getBlacklist

Code samples

POST https://certification-api.iota.works/blacklist HTTP/1.1
Host: certification-api.iota.works
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://certification-api.iota.works/blacklist \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const fetch = require('node-fetch');
const inputBody = '{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd",
  "hash": "999999999999999999999999999999999999999999999999999999999999999999999999999999999"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://certification-api.iota.works/blacklist',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://certification-api.iota.works/blacklist", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /blacklist

Get the blacklist for a certificate.

Body parameter

{
  "issuerId": "AAAAAAAAAAAA",
  "issuerPassPhrase": "P4ssw0rd",
  "hash": "999999999999999999999999999999999999999999999999999999999999999999999999999999999"
}

Parameters

Name	In	Type	Required	Description
issuerId	body	string	true	Who issued the certificates
issuerPassPhrase	body	string	true	The pass phrase for the issuer
hash	body	string	true	The hash of the certificate to get the blacklist

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "reason": 1,
  "details": "Issued with incorrect details"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» success	boolean	true	none	True if the operation was a success, false if it failed
» message	string	true	none	A message explaining the result of the operation
» reason	number	true	none	The reason the certificate is blacklisted, a value from the options
» details	string	true	none	A more detailed description of why the certificate was blacklisted

Example

The process from initial setup to generating your first certificate would be as follows:

• Create a background with the /background endpoint, this will return a backgroundId
• Create a template associating it with the backgroundId using the /template endpoint, this will return a templateId
• Create an issuer with the allowedTemplates set to templateId using the /issuer endpoint.
• Generate a certificate with the /certificate endpoint

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

const API_ENDPOINT = 'https://certification-api.iota.works';
const ADMIN_USER_ID = "ADMIN_USER_ID";
const ADMIN_PASS_PHRASE = "ADMIN_PASS_PHRASE";
const BACKGROUND_PATH = './background.svg';

const ax = axios.create({ baseURL: API_ENDPOINT });
const testNumber = 10;

async function createBackground() {
    console.log("Creating Background");
    const response = await ax.put(`background`, {
        adminId: ADMIN_USER_ID,
        adminPassPhrase: ADMIN_PASS_PHRASE,
        content: fs.readFileSync(BACKGROUND_PATH).toString()
    });

    if (response.data.success) {
        console.log("Created Background", response.data.backgroundId);
        return response.data.backgroundId;
    } else {
        console.error("Failed Creating Background", response.data.message);
    }
}

async function createTemplate(backgroundId) {
    console.log("Creating Template");
    const response = await ax.put(`template`, {
        adminId: ADMIN_USER_ID,
        adminPassPhrase: ADMIN_PASS_PHRASE,
        name: `Template ${testNumber}`,
        backgroundId,
        additionalContent: `template extra ${testNumber}`,
        caption: "Template Caption",
        qrColor: "#0000FF",
        canIssue: true
    });

    if (response.data.success) {
        console.log("Created Template", response.data.templateId);
        return response.data.templateId;
    } else {
        console.error("Failed Creating Template", response.data.message);
    }
}

async function createIssuer(templateId) {
    console.log("Creating Issuer");
    const response = await ax.put(`issuer`, {
        adminId: ADMIN_USER_ID,
        adminPassPhrase: ADMIN_PASS_PHRASE,
        name: `Issuer ${testNumber}`,
        newPassPhrase: `testpass${testNumber}`,
        canIssue: true,
        isAdministrator: false,
        allowedTemplates: [templateId],
        signature: `Issuer ${testNumber}`
    });

    if (response.data.success) {
        console.log("Created Issuer", response.data.issuerId);
        return response.data.issuerId;
    } else {
        console.error("Failed Creating Issuer", response.data.message);
    }
}

async function createCertificate(issuerId, templateId) {
    console.log("Creating Certificate");
    const response = await ax.post(`certificate`, {
        issuerId,
        issuerPassPhrase: `testpass${testNumber}`,
        participant: `Mr Participant ${testNumber}`,
        participationDate: "18/06/2019 - 17/06/2020",
        trainingTitle: `Title of Training ${testNumber}`,
        issuedDate: "18/6/2019",
        templateId
    });

    if (response.data.success) {
        console.log("Created Certificate", response.data.hash, response.data.validationUrl);
    } else {
        console.error("Failed Creating Certificate", response.data.message);
    }
}

(async function () {
    try {
        console.log('One Pass');
        console.log('========');

        const backgroundId = await createBackground();
        if (backgroundId) {
            const templateId = await createTemplate(backgroundId);

            if (templateId) {
                const issuerId = await createIssuer(templateId);

                if (issuerId) {
                    await createCertificate(issuerId, templateId);
                }
            }
        }
    } catch (err) {
        console.error('Request Failed', err.message);
    }
})();

JavaScript Code which demonstrates the above is shown.

You will need to also need to download and store a template such as ./background.svg to run the code.

Changelog

v1.0.11

• Added version check endpoint POST '/'
• Added /docs endpoint

v1.0.10

Most of these changes are to replace bundleHash with hash as we have moved from using the bundle hash to identify a certificate to the tail transaction hash. Where possible the old properties are still supported, but will be deprecated in future versions.

• BUNDLE-HASH in template has been replace with HASH
• /certificate POST response object replaced hash with bundleHash
• /certificate POST request object replaced template with templateId
• /issued response objects items replaced hash with bundleHash
• /issued added the version property of the response object items
  • version 0 is the old hash type which points to a bundle
  • version 1 is the new hash type which points to a tail transaction
• changed blacklist actions to receive hash instead of bundleHash
• /authenticate endpoint includes the version property in its response object

v1.0.9

• First public release