Introduction

Welcome to the VDX Core API, or Core API for short. The Core API is a REST API that provides developers with a simple-to-use interface to several Blockchains for the purpose of issuing Blockchain verifiable credentials. If you already have an existing solution in place, and would like to plug in Blockchain functionality, the Core API is what you need.

In a very summarized flow, you only need to upload your files to the Core API, create a Credential with it, by adding any additional metadata, and issue it onto the Blockchain of your choice. After it has been fully issued and confirmed, the credential is perpetually and irrevocably verifiable.

Every endpoint available on the Core API is described and accompanied by a visual example of how the API responds. For an improved experience when integrating the Core API to your code, you can import our libraries:

• Python: vdx-helper on PyPi

All Python examples used in the examples are from the above library.

The Core API is available in two different environments - the "Demo" and the "Live" environments. The former can be used for free testing, since it is connected to the Testnet Blockchain and does not affect your live data. There is also no limits to the number of requests, however any documents issued through the "Demo" environment have no validity. The "Live" environment is connected to the Mainnet Blockchains, so its use is limited per the subscribed tier or your contract with Vizidox.

For further information on each endpoint, feel free to consult the Core API Swagger UI page, which can also be used to test these endpoints on the Demo environment.

Please check our Privacy Policy for more details on data collection. Furthermore, by using the Core API you are agreeing to our Terms and Conditions.

Endpoint URLs

All endpoints and parameters are the same between both available environments. Although the examples provided in the documentation display the Live environment URL, you just need to switch the domain if you want to use the Demo environment instead.

The API Key used for authentication on each environment is different as well.

Pagination

class PaginatedView(NamedTuple):
    page: int
    total_pages: int
    per_page: int
    total_items: int
    items: List[Object]

JSON Response

{
  "page": 1,
  "total_pages": 1,
  "per_page": 20,
  "total_items": 2,
  "items": [{}]
}

Most of the provided API resources have support for bulk retrievals, such as the "Get All Files" endpoint. The result for these endpoints is always paginated, and they contain common query parameters for managing the pagination.

All of these parameters are fully optional and default values are applied when they are not provided in the request.

Errors

All paginated endpoints return a specific error if any given pagination argument is incorrect:

Tags

The Core API allows the use of tags to further help with filtering and searching for credentials, jobs and certificates. These tags can be added to credentials or jobs, and can then be used to search for all credentials or jobs that contain those specific tags, or certificates created from credentials or issued on jobs with specific tags.

All tags have a format that must be followed:

• They must have 3 or more characters in length
• Only alphanumeric, _ and - characters are allowed
• Within the same credential or job, there can be no duplicate tags

Tags can be directly added to credentials when creating them, or after creation through specific endpoints that are detailed below. Although you cannot add tags to Jobs on creation, they can be added afterward in the same way as credentials.

On retrieval endpoints, tags can be used as query parameters to filter the results. The parameters that can be used are:

Authentication

curl -X POST https://vizidox.com/auth/realms/core-api/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \ 
-d "grant_type=client_credentials&client_secret=<API_KEY>&client_id=<CLIENT_ID>"

curl -X POST https://api-demo.vizidox.com/auth/realms/vizidox/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \ 
-d "grant_type=client_credentials&client_secret=<API_KEY>&client_id=<CLIENT_ID>"

curl -X GET https://vizidox.com/api/<ENDPOINT> -H "Authorization: Bearer <TOKEN>"

curl -X GET https://api-demo.vizidox.com/api/<ENDPOINT> -H "Authorization: Bearer <TOKEN>"

from vdx_helper import VDXHelper

vdx_helper = VDXHelper(url="https://vizidox.com/api", 
                       keycloak_url=https://vizidox.com/auth/realms/core-api/protocol/openid-connect/token,
                       core_api_key=<API_KEY>, core_api_client_id=<CLIENT_ID>)

Make sure to replace <API_KEY> with your API key and <CLIENT_ID> with your Client ID

The VDX Core API uses API Keys to authenticate requests, through the OAuth 2.0 Client Credentials grant. The API Key is provided to you directly, or through your team settings on the VDXapi Portal.

All API requests need to be made over HTTPS and with valid authentication.

First, use your API Key to request an authorization token from our authentication server. Afterward, use that token in any API request.

You should not share your Key with any unauthorized third party, nor post it in any public area such as a repository.

Issuing with Vizidox

With the Vizidox Core API, you can choose to either issue a file, metadata in json format, or both at the same time. A single credential can also be issued with multiple files attached to it as well. Furthermore, the credentials that are created on the system (which contain these files and metadata) can also be linked to one another, creating a Credential Record. This means that you can keep adding new credentials to this Record, updating the data without being able to edit old entries, and these are all linked together.

To issue credentials, the Vizidox API works on a scheduling basis. Instead of manually starting the issuing process when you register a credential on the system, you simply mark these credentials to be issued on a specific Blockchain. All scheduled credentials are issued at the same time when the next issuing date for your partner is. The frequency in issuings is either defined by you when you manage your partner settings on the VDXapi Portal, or directly with Vizidox depending on your contract.

To issue data to the Blockchain, there are three important steps:

• Upload the file you need to certify – optional if you are only issuing metadata;
• Create your credential, by providing the file hash and/or metadata you may wish to add;
• Schedule the credential to be issued on a specific Blockchain.

Each of the endpoints required for these steps are explained in more detail in the Resources section.

Resources

Response

{
  "result": {},
  "meta": {
    "last_update": "Mon, 18 Apr 2022 15:05:00 GMT",
    "date": "Thu, 21 Apr 2022 15:17:27 GMT",
    "message": ":)",
    "version": "2022.04.1",
    "documentation": "https://docs.vizidox.com"
  }
}

All endpoints in the Core API follow a specific format which contains the results itself of the endpoint, as well as an extra field for server information. This field is called "meta", and it contains:

• Last update: The date of the latest update on the Core API
• Date: The current date of the request
• Message: A message with any information regarding breaking changes on specific endpoints.
• Version: The current version of the Core API
• Documentation: A link to the API documentation

Partner

{
  "id": "vizidox",
  "name": "Vizidox"
}

A Partner represents the client sending requests to the Core API. All credentials that are issued by you are associated to your partner ID, and your API Key will only work with the correct partner ID as well.

File

The File Object

{
  "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
  "file_type": "image/jpeg"
}

The File object represents a file uploaded to Vizidox by a Partner. It contains two fields:

The file_type parameter has to follow the MIME standard.

Upload File

curl -X POST "https://vizidox.com/api/files" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.pdf;type=application/pdf" -F "ignore_duplicated=true"

file = vdx_helper.upload_file(file_stream, ignore_duplicated, mapper)

class FileView(NamedTuple):
    file_hash: str
    file_type: Optional[str]

Uploads a file to the Core API, and stores its hash for future issuing. This endpoint will not trigger the issuing process for the uploaded file.

It should be noted that if a file is not used to create a credential, it is automatically deleted from the server after one hour.

HTTP Request

POST https://vizidox.com/api/files

Returns

If successful, the HTTP response is a 201 CREATED, along with a file object.

Errors

Get All Files

curl -X GET "https://vizidox.com/api/files" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

file = vdx_helper.get_files(mapper, file_hash, pagination)

class PaginatedView(NamedTuple):
    page: int
    total_pages: int
    per_page: int
    total_items: int
    items: List[FileView]

Obtain all files uploaded by the Partner. Includes the pagination arguments.

HTTP Request

GET https://vizidox.com/api/files

Pagination

sort_by parameter can be filled in with:

• uploaded - the date the file was uploaded

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of files.

Get A File

curl -X GET "https://vizidox.com/api/files/<HASH>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>

file = vdx_helper.get_file_attributes(file_hash, mapper)

Obtains a specific file

HTTP Request

GET https://vizidox.com/api/files/<HASH>

Returns

If successful, the HTTP response is a 200 OK, along with a file object

Errors

Credential

The Credential Object

{
      "uid": "123e4567-e89b-12d3-a456-426655440000",
      "title": "Credential Title",
      "metadata": {"Name":  "Special Credential"},
      "files": [
        {
          "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
          "file_type": "image/jpeg"
        }
      ],
      "credentials": [
        {
          "uid": "123e4567-e89b-12d3-a456-426655440000",
          "title": "Different Credential Title",
          "metadata": {},
          "files": [
            {
              "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
              "file_type": "application/pdf"
            }
          ],
          "credentials": [{}],
          "upload_date": "2020-01-11T15:34:05.811954+00:00",
          "tags": [
            "tagA"
          ]
        }
      ],
      "upload_date": "2020-02-11T15:34:05.811954+00:00",
      "tags": [
        "tagA",
        "tagB"
      ],
      "expiry_date": "2025-02-11T15:34:05.813229+00:00"
}

Fingerprint of the file, including additional data provided by the Partner. Optionally, can only contain metadata without a file.

Create Credential

curl -X POST "https://vizidox.com/api/credentials" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
  -H  "Content-Type: application/json" -d "{  \"title\": \"Example Title\",  \"metadata\": {\"Name\": \"Example\"}, \ 
  \"files\": [\"056f32ee5cf49404607e368bd8d3f2af\"],  \"credentials\": [\"123e4567-e89b-12d3-a456-426655440000\"],  \
  \"tags\": [\"TagA\"],  \"expiry_date\": \"2020-02-11T15:34:05.814607+00:00\"}"

credential = vdx_helper.create_credential(title, metadata, tags, file_hashes, credential_uids, expiry_date, mapper)

class CredentialView(NamedTuple):
    uid: UUID
    title: str
    metadata: dict
    files: List[FileView]
    credentials: List['CredentialView']
    upload_date: datetime
    tags: List[str]
    expiry_date: Optional[datetime]

Credential Creation Request Body

{
  "title": "Example Credential",
  "metadata": {"Name": "Example"},
  "files": ["5d6abece8532c71bb51a749a6af06de7"],
  "credentials": ["123e4567-e89b-12d3-a456-426655440000"],
  "tags": ["tagA"],
  "expiry_date": "2030-01-01T15:34:05.814607+00:00"
}

Creates a credential on the Core API, either from a file or from metadata. This endpoint will not trigger the issuing process for the created credential. If no file is provided, the metadata dictionary can not be empty.

HTTP Request

POST https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 201 CREATED, along with a credential object.

Errors

Create and Schedule Credential

curl -X POST "https://vizidox.com/api/credentials/schedule/<engine>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
  -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.pdf;type=application/pdf" \
  -F "credential_details={\"title\": \"Example Title\", \"metadata\": {\"Name\": \"Example\"}, \ 
  \"credentials\": [\"123e4567-e89b-12d3-a456-426655440000\"], \"tags\": [\"TagA\"], \
  \"expiry_date\": \"2029-02-11T15:34:05.814607+00:00\", \"ignore_duplicate\": \"true\"}"

Credential Schedule Request Body

{
  "title": "Example Credential",
  "metadata": {"Name": "Example"},
  "credentials": ["123e4567-e89b-12d3-a456-426655440000"],
  "tags": ["tagA"],
  "expiry_date": "2030-01-01T15:34:05.814607+00:00",
  "ignore_duplicate": "true"
}

Creates a new credential on the Core API, either from a file uploaded directly on the same request, or from the provided metadata. After the credential is created, it is automatically scheduled for issuing on the provided engine. This endpoint will not trigger the issuing process for the created credential. If no file is provided, the metadata dictionary can not be empty.

HTTP Request

POST https://vizidox.com/api/credentials/schedule/<engine>

Returns

If successful, the HTTP response is a 201 CREATED, along with a Credential object.

Errors

Get All Credentials

curl -X GET "https://vizidox.com/api/credentials" -H  "accept: application/json" -H "authorization: Bearer <TOKEN>"

credentials = vdx_helper.get_credentials(mapper, metadata, uid, start_date, 
                                         end_date, and_tags, or_tags, pagination)

Obtains all credentials previously created by the Partner. Includes the pagination arguments.

HTTP Request

GET https://vizidox.com/api/credentials

Pagination

sort_by parameter can be filled in with (Default is created_date):

• title - the title of the credential
• upload_date - The date the credential was created

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of credentials.

Get A Credential

curl -X GET "https://vizidox.com/api/credentials/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

credential = vdx_helper.get_credential(cred_uid, mapper)

Obtains a specific credential

HTTP Request

GET https://vizidox.com/api/credentials/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with a credential object

Errors

Add Tags

curl -X PATCH "https://vizidox.com/api/credentials" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
          -H  "Content-Type: application/json" -d "{\"credentials\": [{\"credential_uid\": \"123e4567-e89b-12d3-a456-426655440000\", \
               \"tags\": [\"tagA\",\"tagB\",\"tagC\"]}]}"

updated_tags = {"credentials": [{"credential_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.update_credential_tags(updated_tags)

Tag Addition Request Body

{
  "credentials": [
    {
      "credential_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "credential_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Add new tags to a credential. This endpoint can be used to update more than one credential, by providing a list in the correct format on the body of the request.

Old tags will not be deleted.

HTTP Request

PATCH https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 200 OK with no additional content

Errors

Replace Tags

curl -X PUT "https://vizidox.com/api/credentials" -H  "accept: application/json" -H  "Content-Type: application/json" \
             -H  "authorization: Bearer <TOKEN>" \
             -d "{  \"credentials\": [{\"credential_uid\": \"123e4567-e89b-12d3-a456-426655440000\",\"tags\": [\"tagA\",\"tagB\",\"tagC\"]}]}"

new_tags = {"credentials": [{"credential_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.replace_credential_tags(new_tags)

Tag Replacement Request Body

{
  "credentials": [
    {
      "credential_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "credential_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Replace all the tags in a credential. This endpoint can be used to update more than one credential, by providing a list in the correct format on the body of the request.

Old tags are all deleted.

HTTP Request

PUT https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 200 OK with no additional content

Errors

Delete Credential Tags

curl -X PATCH "https://core-dev.vizidox.com/api/credentials/<UID>/delete_tag?tag=<TAG>>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

vdx_helper.delete_credential_tag(credential_uid, tag)

Deletes the tag from the given credential.

HTTP Request

PUT https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 200 OK with no additional content

Errors

Schedule Credentials

curl -X POST "https://vizidox.com/api/credentials/schedule" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
             -H  "Content-Type: application/json" -d "{\"engine\": \"bitcoin\", \"credentials\": [\"123e4567-e89b-12d3-a456-426655440000\"]}"

job = vdx_helper.schedule_credentials(engine, credentials, mapper)

Credential Schedule Request Body

{
  "engine": "bitcoin",
  "credentials": [
    "123e4567-e89b-12d3-a456-426655440000",
    "ce8bd4a4-e011-43ca-b775-d9569c690c42"
  ]
}

Schedules one or more existing credentials on the Core API. The given credentials will be added to the current scheduled job, to be issued at the next issuing schedule.

A Credential cannot be issued more than once on the same Blockchain Engine, however it can be issued over multiple engines.

HTTP Request

POST https://vizidox.com/api/credentials/schedule

Returns

If successful, the HTTP response is a 201 CREATED, along with a job object.

Errors

Unschedule Credential

curl -X DELETE "https://vizidox.com/api/credentials/<UID>/unschedule/<engine>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

job = vdx_helper.schedule_credentials(engine, credentials, mapper)

Unschedules an existing (and previously scheduled) Credential from the given Blockchain engine. If the Credential is not scheduled nor issued on any other Blockchain engine, then it is also deleted.

HTTP Request

DELETE https://vizidox.com/api/credentials/<UID>/unschedule/<engine>

Returns

If successful, the HTTP response is a 200 OK.

Errors

Job

The Job Object

{
  "uid": "123e4567-e89b-12d3-a456-426655440000",
  "partner": {
    "id": "vizidox",
    "name": "Vizidox"
  },
  "chain": "bitcoin",
  "tags": ["tagA"],
  "status": "finished",
  "start_date": "2020-02-11T15:34:05.814703+00:00",
  "issued_date": "2020-02-11T15:34:08.814719+00:00",
  "finished_date": "2020-02-11T15:38:05.814731+00:00",
  "failed_date": null,
  "created_date": "2020-02-10T18:34:05.814743+00:00",
  "scheduled_date": null
}

A Job is a Blockchain transaction containing a bundle of credentials. A job has several status:

• Scheduled - The bundle of credentials on the Job have yet to be issued on the Blockchain, but will be issued on the next schedule.
• Started - The Blockchain issuing process has started and is in progress.
• Unconfirmed - The Blockchain issuing process has successfully finished, but the corresponding transaction has yet to be confirmed on the Blockchain.
• Finished - The Blockchain issuing transaction has been confirmed. All credentials issued in this bundle will fully pass the verification process. This status is final.

• Failed - Something went wrong with the Blockchain issuing process, and the credentials have not been issued. They will have to be added again to the next scheduled job. This status is final.

  Field	Description
  uid	The unique identifier of the job
  partner	The partner issuing the job
  chain	The blockchain engine to issue the job on
  tags	Tags to identify the job
  status	Current status of the job
  created_date	Date the job was created at
  start_date	Date the job started
  issued_date	Date the job finished issuing
  finished_date	Date the job was confirmed on the Blockchain, if in the finished status
  failed_date	Date the job failed, if in the failed status
  scheduled_date	Date the job is scheduled to run, if in the scheduled status

Get All Jobs

curl -X GET "https://vizidox.com/api/jobs" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

# start_date and end_date will be used on the issued_date_from and issued_date_until parameters
jobs = vdx_helper.get_jobs(mapper, job_status, uid, start_date, end_date, and_tags, or_tags, pagination)

Obtains all the Partner's jobs. Includes the pagination arguments and tags to filter by.

HTTP Request

GET https://vizidox.com/api/jobs

Pagination

sort_by parameter can be filled in with (default is created_date):

• status - Status of the job
• chain - Blockchain engine the job was issued on
• start_date - Date the job started issuing
• issued_date - Date the job completed issuing
• ready_date (=finished_date) - Date the Job's Blockchain transaction was confirmed
• failed_date - Date the Job failed issuing

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of jobs.

Get A Job

curl -X GET "https://vizidox.com/api/jobs/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

job = vdx_helper.get_job(job_uid, mapper)

Obtains a specific Job

HTTP Request

GET https://vizidox.com/api/jobs/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with a job object.

Errors

Add Tags

curl -X PATCH "https://vizidox.com/api/jobs" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
              -H  "Content-Type: application/json" \
              -d "{\"jobs\": [{\"job_uid\": \"123e4567-e89b-12d3-a456-426655440000\",\"tags\": [\"tagA\",\"tagB\",\"tagC\"]}  ]}"

updated_tags = {"jobs": [{"job_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.update_job_tags(updated_tags)

Tag Addition Request Body

{
  "jobs": [
    {
      "job_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "job_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Add new tags to a job. This endpoint can be used to update more than one job, by providing a list in the correct format on the body of the request.

Old tags will not be deleted.

HTTP Request

PATCH https://vizidox.com/api/jobs

Returns

If successful, the HTTP response is a 200 OK with no additional content.

Errors

Replace Tags

curl -X PUT "https://vizidox.com/api/jobs" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
            -H  "Content-Type: application/json" \
            -d "{\"jobs\": [{\"job_uid\": \"123e4567-e89b-12d3-a456-426655440000\",\"tags\": [\"tagA\",\"tagB\",\"tagC\"]}]}"

new_tags = {"jobs": [{"job_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.replace_job_tags(new_tags)

Tag Replacement Request Body

{
  "jobs": [
    {
      "job_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "job_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Replace all the tags in a job. This endpoint can be used to update more than one job, by providing a list in the correct format on the body of the request.

Old tags are all deleted.

HTTP Request

PUT https://vizidox.com/api/jobs

Returns

If successful, the HTTP response is a 200 OK with no additional content.

Errors

Get Credentials in Job

curl -X GET "https://vizidox.com/api/jobs/<UID>/credentials" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

credentials = vdx_helper.get_job_credentials(job_uid, and_tags, or_tags, mapper, pagination)

Obtains all credentials issued in a specific job. Includes the pagination arguments.

HTTP Request

GET https://vizidox.com/api/jobs/<UID>/credentials

Pagination

sort_by parameter can be filled in with (Default is created_date):

• status - The current status of the job
• chain - The blockchain engine the job was issued on
• created_date - The date the job was created
• start_date - The date the issuing process of the job started
• issued_date - the date the issuing process of the job finished
• ready_date - The date the issuing transaction of the job was confirmed on the blockchain
• failed_date - The date the job issuing failed

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of credentials.

Get Certificates in Job

curl -X GET "https://vizidox.com/api/jobs/<UID>/certificates" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

certificates = vdx_helper.get_job_certificates(job_uid, and_tags, or_tags, mapper, pagination)

Obtains all certificates issued in a specific job. Includes the pagination arguments.

HTTP Request

GET https://vizidox.com/api/jobs/<UID>/certificates

Pagination

sort_by parameter can be filled in with (Default is issued_date):

• issued_date - the date the certificate was issued on
• chain - The Blockchain engine the certificate was issued on

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of certificates.

Issue Job

curl -X POST "https://api-demo.vizidox.com/api/jobs/immediate" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
  -H  "Content-Type: application/json" -d "{  \"engine\": \"bitcoin\"}"

Issue Job Request Body

{
  "engine": "bitcoin"
}

Triggers the issuing process immediately on a certain blockchain engine. All the scheduled credentials for that engine will be issued. Only available on the demo environment for testing purposes.

HTTP Request

POST https://api-demo.vizidox.com/api/jobs/immediate

Returns

If successful, the HTTP response is a 201 CREATED, along with a job object.

Errors

Certificate

The Certificate Object

{
  "certificate": {
    "uid": "e2f52c36-7d39-48d7-8617-030891304cc2",
    "partner": {
      "id": "vizidox",
      "name": "Vizidox"
    },
    "credential": {
      "uid": "29d6f14e-a770-4f1c-8d6e-2e1aa4e9881a",
      "title": "Credential Title",
      "metadata": {"approved_by":  "John Smith"},
      "files": [
        {
          "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
          "file_type": "image/jpeg"
        }
      ],
      "credentials": [],
      "upload_date": "2020-02-11T15:34:05.811954+00:00",
      "tags": [
        "tagA",
        "tagB",
        "tagC"
      ],
      "expiry_date": "2025-02-11T15:34:05.813229+00:00"
    },
    "issued_date": "2020-02-11T15:34:05.813217+00:00",
    "signature": "H+oPfLTKcG19O9yGgV1ftXPRXTvsMRXd22Uw8vyTuSlOTff+HUwvB8yFuKw/YzAFShDIvsjn4XBmsVGTb7iz2I8="
  },
  "revoked_date": null,
  "last_verification": {
    "status": "ok",
    "timestamp": "2021-05-07T19:21:04.813289+00:00"
  }
}

A Certificate is a verifiable descriptor for a credential issued over the Blockchain. The Certificate will contain all relevant data to connect the Credential to a Blockchain transaction. There is a one to one relationship between certificates, credentials and Blockchain engines: Each issued Credential has one Certificate per Blockchain engine.

Get All Certificates

curl -X GET "https://vizidox.com/api/certificates" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

certificates = vdx_helper.get_certificates(mapper, job_uid, cred_uid, uid, start_date, end_date, and_credential_tags, 
                                           or_credential_tags, and_job_tags, or_job_tags, verification_status, pagination)

Obtains all certificates issued by the partner. Includes the pagination arguments.

You can also use either the corresponding Credential or Job tags to search for certificates, even though the Core API does not support the addition of tags per certificates. These work in the same way as all other endpoints which contain tags as a filter option:

• and_credential_tags + or_credential_tags: To filter certificates of credentials that are identified by the given tags.
• and_job_tags + or_job_tags: To filter certificates issued on jobs that are identified by the given tags.

HTTP Request

GET https://vizidox.com/api/certificates

Pagination

sort_by parameter can be filled in with (Default is issued_date):

• issued_date - the date the certificate was issued on
• chain - The Blockchain engine the certificate was issued on

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of certificates.

Download Certificate JSON

curl -X GET "https://vizidox.com/api/certificates/<UID>/download" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

certificate_json = vdx_helper.download_certificate(certificate_uid)

Downloads a text file containing all relevant certificate data in a JSON format. Can also be called the proof file, and is usable for verification on the Core API.

HTTP Request

GET https://vizidox.com/api/certificates/<UID>/download

Returns

If successful, the HTTP response is a 200 OK, along with a text file containing a JSON with the certificate data.

Errors

Verification

The Verification Object

{
  "verification": {
    "certificate": 
        {
          "name": "Checking certificate integrity",
          "description": {
            "hash_function": "SHA256",
            "actual_hash": "3fb4ef9b874803631b0fdd41f42bac952a2f5e9501d4e8ff3d0f13bd113435aa",
            "expected_hash": "3fb4ef9b874803631b0fdd41f42bac952a2f5e9501d4e8ff3d0f13bd113435aa"
          },
          "status": "passed"
        },
    "blockchain": 
        {
          "name": "Checking certificate is anchored to the blockchain",
          "description": {
            "actual_root": "1677894799b64e8f3c8ff1fa519ae3dab489fa86e2d6e2794e7c08a10290de95",
            "certificate_root": "1677894799b64e8f3c8ff1fa519ae3dab489fa86e2d6e2794e7c08a10290de95",
            "tx_id": "42d9914d9eee0d45ce870e1f56c0c5b71167754f03cc789bec8392fe20673730",
            "tx_url": "https://blockchair.com/bitcoin/testnet/transaction/42d9914d9eee0d45ce870e1f56c0c5b71167754f03cc789bec8392fe20673730",
            "confirmations": "3944"
          },
          "status": "passed"
        },
    "issuer": 
        {
          "name": "Checking issuer authenticity",
          "description": {
            "issuer_name": "Vizidox",
            "signature_scheme": "ECDSA",
            "partner_public_key": "mgiYnTTZmMG6SJAEBKd724YWFMLDrCF1Y1",
            "message": "c3c47e03d650bc3feffa24c5a2620ba1b4f894030df2ab2c6a809e7aa84c8c06",
            "signature": "H7E7JBfVt68MMLm9RlVXphPVsnwriC1DFF2iXOQ2VipDMWWd73agLskIc241UEplnhm/u7ChxkdoTUqqAOP0kWQ="
          },
          "status": "passed"
        },
    "file": 
        {
          "name": "Checking file integrity",
          "description": {
            "hash_function": "SHA3-256",
            "expected_file_hash": "5f476523425b99e128ea4de78763430e66c2bb75f99571b181104791a4f843f3",
            "actual_file_hash": "5f476523425b99e128ea4de78763430e66c2bb75f99571b181104791a4f843f3"
          },
          "status": "passed"
        },
    "expiry": 
        {
          "name": "Checking expiry date",
          "description": {
            "issued_date": "2021-09-24T14:30:08.056293+00:00",
            "expiry_date": null
          },
          "status": "passed"
        },
    "revocation": 
        {
          "name": "Checking revocation date",
          "description": {
            "is_revoked": false,
            "revocation_address": "mniEnS85X1iagmYYPNYDR9djtDufriEF2H",
            "revocation_address_url": "https://blockchair.com/bitcoin/testnet/address/mniEnS85X1iagmYYPNYDR9djtDufriEF2H",
            "revocation_date": null
          },
          "status": "passed"
        }
  },
  "result": {
    "status": "ok",
    "timestamp": "2021-10-21T14:45:55.207146+00:00"
  }
}

Verification is the process through which any issued credential can be validated. This only applies to credentials that have been fully issued on the Blockchain, so they cannot be simply scheduled for issuing.

The verification consists of six different steps, and can result in several results:

• Ok - All steps fully passed.
• Pending - At least one step is still pending some action; for example, if the Blockchain transaction is yet to be confirmed, the corresponding step will result in a pending status.
• Expired - The credential has expired, per the defined expiry date provided on creation.
• Revoked - The credential and its corresponding certificate has been revoked, so it is no longer considered valid.
• Failed - At least one verification step failed, meaning that Vizidox cannot guarantee the credential's validity.
• Error - An unexpected error occured during the verification. Contact with Vizidox support if this problem persists.

The obtained final result of verification will depend on the result of each individual verification step. If one step fails during the process, then no more steps will be tested since the credential is no longer considered valid by default. The six executed steps are:

Each of these steps have their own status at the end of the verification, and these are used to determine the final status. The possible verification step status are:

• Not Started - The step was skipped due to an earlier step failing.
• Passed - The step passed.
• Pending - The validation is still pending some other action, such as Blockchain confirmation.
• Failed - The step failed.
• Error - An error occurred during the execution.

Verify By Certificate UID

curl -X GET "https://vizidox.com/api/verify/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

verification = vdx_helper.verify_by_uid(certificate_uid, mapper)

Verifies a Certificate via its unique identifier

HTTP Request

GET https://vizidox.com/api/verify/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with the verification result

Errors

Verify By Credential UID

curl -X GET "https://vizidox.com/api/verify/credential/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

verification = vdx_helper.verify_by_credential_uid(credential_uid, mapper, pagination)

Verify all certificates corresponding to the credential, via the credential's unique identifier. Includes the pagination arguments.

HTTP Request

GET https://vizidox.com/api/verify/credential/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with the verification result

Errors

Verify By Certificate File

curl -X POST "https://vizidox.com/api/verify/upload/certificate" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>>" -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.json;type=application/json"

verification = vdx_helper.verify_by_certificate(filename, file_stream, file_content_type, mapper)

Verifies a specific certificate, by uploading its certificate proof file

HTTP Request

POST https://vizidox.com/api/verify/upload/certificate

Returns

If successful, the HTTP response is a 200 OK, along with the verification result

Errors

Verify By File

curl -X POST "https://vizidox.com/api/verify/upload/file" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>>" -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.pdf;type=application/pdf"

verification = vdx_helper.verify_by_file(filename, file_stream, file_content_type, mapper)

Verifies all certificates of the uploaded file Includes the pagination arguments.

HTTP Request

POST https://vizidox.com/api/verify/upload/file

Returns

If successful, the HTTP response is a 200 OK, along with a paginated list of all verification results

Errors

Revocation

All issued credentials can be revoked if you need to. If for example, there was some error in the issued data and it should not be considered valid, revoking its corresponding certificate will guarantee that all future verifications fail.

Revoke Certificate By UID

curl -X POST "https://vizidox.com/api/certificates/<UID>/revoke" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

revoked_date = vdx_helper.revoke_certificate(cert_uid)

Revokes a certificate, identified by its UID

HTTP Request

POST https://vizidox.com/api/certificates/<UID>/revoke

Returns

If successful, the HTTP response is a 200 OK, along with the revocation date.

Errors

Revoke Certificate By Credential UID

curl -X POST "https://vizidox.com/api/credentials/<UID>/revoke/{engine}" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

Revokes the credential's certificate for the given Blockchain engine.

HTTP Request

POST https://vizidox.com/api/credentials/<UID>/revoke/{engine}

Returns

If successful, the HTTP response is a 200 OK, along with the revocation date.

Errors