Request WEB API Access (CBR)

Table of Contents

Introduction #

The pre-conditions for a consuming (client) system to be able to use any of the eCert APIs are as follows: 

  • The consuming system must belong or be associated with a registered business in the Central Business Register (https://cbr.ecert.co.za/) 
  • A client system calling any of the eCert APIs will need to be registered as a client in the User Authentication Service (UAS) and issued a valid client Id and client secret to be able to consume the endpoints
  • All request calls to the APIs will be authenticated using a JWT (JSON Web token) bearer token over OAuth 2.0 protocol (see How To Connect user guide) 

This user guide is designed to give instructions on how users can request for API access credentials for CBR registered businesses which they can then use to consume all APIs in the eCert ecosystem.

Web API Access #

To set up Web API access for a business the user needs to login to the Central Business Register(CBR) at  https://cbr.ecert.co.za/Account/Login.

To request web API access for a business under the menu navigate to API Access as shown in the figure below.

Figure 1: CBR Menu

Click on API Access link to drill down the menu options. The API access menu items will show 2 sub-menu items as follows:

View API Access Details: lists all businesses that the user is associated with to have API access, the user can select a specific business to view API details for that business

Request API Access: this option allows the user to request API access for businesses they manage, this will generate the client Id and client secret

Request API Access #

To request API access for a business, select the Request API Access option as illustrated in the figure below:

Figure 2: Request API Access menu item

On clicking the link, the Request API Access page will open as follows:

Figure 3: Request Access Page

The information required on this page is as shown below:

Business Name: select the businessto register for API access

Declaration: check the declaration checkbox to agree to the declaration

NB: Request Access button only activates when Declaration checkbox is checked

Click Request Access button to generate API access credentials

If the business is already linked “Client already exists!” message  is returned, otherwise on success, the  user is redirected to the API Access Details page as shown below:

Figure 4: View API Details

The API Access Details displayed on the page are as follows:

Business Name:       Name of the business
Business ID:              The unique numeric business ID used when submitting to APIs
eCert Business ID:   A unique business identifier on eCert
Client ID:                    A unique ID used together with Base 64 Secret to authorize and get token
Base 64 Secret:       Secret used together with Client ID to authorize and get token

The ClientId and ClientSecret, in turn, will be used by the client to authorize and get a token. With a valid token, the client system can call an API endpoint on the TUR Web API provided all the required parameters are presented. 

View API Access Details #

To view the API Access Details for a business select the View API Access Details option as illustrated in the figure below:

Figure 5: View API Access Detail Menu Option

On clicking the My Businesses the page opens, listing all the businesses connected to the logged-in user which have API Access. To view  API access for any of the listed business click the view icon  .

Figure 6: API Businesses Listing

On clicking the view icon the API Access Details namely Business Name, Business ID, eCert Business ID, Client ID, Base 64 Secret displayed as shown in figure 4.

Was this guide helpful?