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.
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:
On clicking the link, the Request API Access page will open as follows:
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:
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:
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 .
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.