https://portal.nectar.software
https://api.nectar.software
https://nectar.software
Nectar API is a highly performant, cloud-based, REST STS tokens generation tool. As part of the Nectar REST API, Java, Python (in development) and PHP (in development) SDKs are available to allow 3rd parties to generate tokens on demand using Nectar’s scalable infrastructure. Nectar is IEC 62055-41:2018 compliant tokens.
This document provides a description of the Nectar REST API while providing examples of possible values that can be used as payloads for the various requests. Credentials to the Nectar API will be managed using https://portal.nectar.software while API requests will be made against https://api.nectar.software.
Check the Get Started tutorial to see how to use the Nectar API SDKs to generate STS tokens.
PUT, POST, GET, DELETE
200 Request was successful
400 Bad Request, missing required parameters
401 Unauthorized
403 Forbidden
404 Resource Not Found
405 Method Not Allowed
500 Internal Server Error
The first step in using the Nectar API for token generation will be to create an account at https://portal.nectar.software. The next step will be to create your 4096 bit RSA keys PKI private-public key pair and a 128 bit AES symmetric key. The PKI public key and symmetric key must be kept confidential. Once these are created, an STS configuration yaml with the format below will need to be created. The STS configuration yaml file can have any name.
---
name: [0-9a-zA-Z\-]{1.}
key_expiry_no: [0-255]
encryption_algorithm: [sta|dea|misty]
token_carrier_type: [numeric]
decoder_key_generation_algorithm: [01,02,03,04]
tariff_index: [[0-9]{2}]
key_revision_no: [[1-9]{1}]
vending_key: [[0-9a-f]{16}]
supply_group_code: [[0-9]{6}]
key_type: [0-3]
base_date: [1993,2014,2035]
issuer_identification_no: 600727
For each of the STS configuration items above, regex commands are indicated to show the expected format.
The following steps are then performed:
Each of the three base64 encoded outputs above are submitted using the Nectar API portal page at Configurations using the tab indicated `Option 1: Upload STS Config File(Recommended)`.
Alternatively, the Configurations page also does have a tab indicated as
`Option 2: Fill In STS Configuration` where individual elements of an STS configuration can be entered. These STS configurations are encrypted on the browser client based on the model described above before being submitted to the Nectar API.
An STS configuration can also be created by using any of the Nectar API SDKs. The example below shows the Nectar API Java SDK in use to create an STS configuration.
public void createconfiguration() {
final String KEY = "4d4...229";
final String SECRET = "8d3...e0";
Nectar nectar = new Nectar(KEY, SECRET);
String yamlConfig = "---\n" +
"name: example_config\n" +
"key_expiry_no: 255\n" +
"encryption_algorithm: sta\n" +
"token_carrier_type: numeric\n" +
"decoder_key_generation_algorithm: 04\n" +
"tariff_index: 01\n" +
"key_revision_no: 1\n" +
"vending_key: 0123456789abcdef\n" +
"supply_group_code: 123456\n" +
"key_type: 3\n" +
"base_date: 2035\n" +
"issuer_identification_no: 600727";
String symmetricKey = "v....Th";
String privateKey = "\"MIIJQg...iFDkTRMP4Regv6aYfWAMQo0Q==\";";
Configuration configuration = nectar.getConfigurationsFactory()
.createConfiguration(yamlConfig, symmetricKey, privateKey);
System.out.println(String.format("Create Configuration\n====================\n%s\n", configuration));
}
The vending_key uses big endian format. And finally, a POST REST request can also be made to the endpoint https://api.nectar.software/configurations as shown below.
curl --request POST \
--url https://api.nectar.software/v1/config\
--header 'authorization: NECTAR decc...266:OTZkZm...RiZDAwMQ==' \
--header 'content-md5: F3216235710FA290C6508C0BFA8B4041' \
--header 'content-type: application/json' \
--header 'date: Thu, 15 Aug 2020 18:48:58 GMT' \
--header 'nonce: 2659c837e161e039ecf23fe47e6db42f' \
--header 'type': 'sts',
--data '{
"data": "base64(symmetric_key(sts_config_yaml))",
"digest": "base64(sha_256(sts_config_yaml)),
"Key": "base64(nectar_public_key(symmetric_key)).
}'
Kindly note that the last two methods require that the Nectar API account created at https://portal.nectar.software have the permission `Create Configuration` assigned to the credential used. Each credential has a unique guid KEY and SECRET. Credentials can be managed at https://portal.nectar.software/credentials .
An STS configuration_ref will then be generated. All STS configurations are stored encrypted by the Nectar API in a virtual cloud HSM and the details of this STS configuration will never be visible to any user, including yourself as the creator. If forgotten, or require modification, then a new set of STS configurations will have to be created and the old ones deactivated from the Configurations page.
To create a Nectar API account, a developer can use the registration form at https://portal.nectar.software/register or make a REST request to the Nectar API or using a Nectar SDK. The examples below show how to use each of the three methods.
curl --request POST \
--url https://api.nectar.software/v1/user \
--header 'content-type: application/json' \
--data '{
"first_name":"John",
"last_name":"Doe",
"username":"username",
"password":"password",
"phone_no":"0700100100",
"email":"info@email.com",
"activated": false,
"image_url":"https://s3.aws.com/avatar.jpeg"
}'
This REST API call returns a user_ref that can be used in subsequent REST API calls.
public void createUser() {
final String KEY = "4d49b...bb229";
final String SECRET = "8d31...52e0";
Nectar nectar = new Nectar(KEY, SECRET);
Map<String, Object> params = new HashMap<>();
params.put("first_name", "first_name");
params.put("last_name", "last_name");
params.put("username", "username");
params.put("password", "password");
params.put("phone_no", "0700100100");
params.put("image_url", "https://image.url");
params.put("email", "user@email.com");
params.put("activated", true);
String createdUserRef = nectar.getUsersFactory().createUser(params);
System.out.println(String.format("Create User\n====================\n%s\n", createdUserRef));
}
A credentials key pair must be created and managed using the portal at https://portal.nectar.software and the desired set of permissions added to each credential. This key pair is used to authenticate REST API calls and must be kept confidential. Each key pair consists of a consumer key and consumer secret.
With a Nectar API credentials key pair, a developer can then make a call to the Nectar API using REST requests or using a Nectar SDK. An authorization header created using a valid key and secret credentials pair must be included in each API call. If a developer uses a Nectar SDK, then authorization is automatically handled and the only requirement is that a valid credentials key pair is provided.
The examples below show an example of how to make a class 0, subclass 0 (TransferElectricity) token request using an authenticated REST API call and via the Nectar Java SDK.
curl --request POST \
--url https://api.nectar.software/v1/token?class=0&subclass=0 \
--header 'authorization: NECTAR decc...266:OTZkZm...RiZDAwMQ==' \
--header 'content-md5: F3216235710FA290C6508C0BFA8B4041' \
--header 'content-type: application/json' \
--header 'date: Thu, 15 Aug 2020 18:48:58 GMT' \
--header 'nonce: 2659c837e161e039ecf23fe47e6db42f' \
--data '{
"tid": "17/03/2020 07:29:21",
"random_no": 5,
"amount": 100.23,
"config_ref": "087e74c1-2270-45a4-b7d3-66339354f4fc",
"is_stid": true
}'
Or using the Nectar Python SDK
nectar.getTokenFactory().generateElectricityToken(
Instant.now, // TID
5, // random_no
100.23, // amount
"08...f4fc" // config_ref
false) // is_stid
All Nectar API requests must be authenticated and authorized. If using the Nectar REST API endpoints, authentication is done by passing valid Authorization and nonce headers. If any of the Nectar SDKs are used, authentication will be performed automatically by the SDK provided a valid consumer key and secret key pair are provided.
Nectar uses HMAC Authentication using SHA256 (hmac_sha256) to ensure that only valid requests are made to the REST endpoints. A NectarCredentialsKey is used to identify the user and a NectarCredentialsSecret is used in generating the hash value. A nonce must be provided for every request to the Nectar API to prevent replay attacks. In every request to the Nectar API where authentication is required, an Authorization header must be passed created using the following components:
"Authorization: NECTAR" + NectarCredentialsKey + ":"
+ base64(hmac_sha256(HTTP_VERB
+ PATH
+ CONTENT-MD5
+ CONTENT-TYPE
+ DATE
+ nonce), NectarCredentialsSecret)
This creates a HTTP request similar to
GET /v1/token HTTP/1.0
Authorization: NECTAR b74...e68d:ZmMzMjI5YjJiODI2YTR...2QwM3ZjBhMjAzNQ==
Content-Md5: 5AE35AEBE055E462B3742A3A34E062DA
Content-Type: application/json
Date: Thu, 15 Aug 2020 18:48:58 GMT
Nonce: bb5dc8842ca31d4603d6aa11448d1654
In addition, the required set of permissions must be assigned for each credential. The following lists the set of permissions supported.
Permission | Identifier | Notes |
Generate Token | generate_token | Permission to generate tokens |
Create Credentials | create_credentials | Permission to create credentials |
Get Token | get_token | Permission to obtain token |
Generate Token | generate_token | Permission to generate token |
Get User | get_user | Permission to get user |
Create User | create_user | Permission to create user |
Get Public Keys | get_public_keys | Permission to get public keys |
Get Notifications | get_notifications | Permission to get notifications |
Get Credits | get_credits | Permission to get credits |
Get Transactions | get_transactions | Permission to get transactions |
Get Credentials | get_credentials | Permission to get credentials |
Get Configurations | get_configurations | Permission to get configurations |
Update user | update_user | Permission to update user |
Delete user | delete_user | Permission to delete user |
Create Public Keys | create_public_keys | Permission to create public keys |
Activate Public Keys | activate_public_keys | Permission to activate public keys |
Deactivate Public Keys | deactivate_public_keys | Permission to deactivate public keys |
Set notifications read status | set_notifications_read_status | Permission to set notification read status |
Activate credentials | activate_credentials | Permission to activate credentials |
Deactivate credentials | deactivate_credentials | Permission to deactivate credentials |
Create configurations | create_configurations | Permission to create configurations |
Activate configurations | activate_configurations | Permission to activate credentials |
Deactivate configurations | deactivate_configurations | Permission to deactivate credentials |
/v1/tokens
Request
Parameter Type
application/json
Body
{
class 0, subclass 0-2 (TransferCredit token)
{
"class": "0",
"subclass": "[0-2]",
"token_id": [[0-9]{2}\/[0-9]{2}\/[0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2}]
"amount" : [[0-9]{9}\.[0-9]{2}],
"random_no" : [0-9], // optional
"is_stid" : [true|false], // optional
"config_ref": "[a-fA-F0-9\-]{1,}" // config ref
}
class 1, subclass 0-1 (InitiateMeterTest/Display tokens)
{
"control": [0-9]{2} | [0-9]{4}
"manufacturer_code": [1-18],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
class 2, subclass 0 (SetMaximumPowerLimit)
{
"maximum_power_limit": [0-65535],
"token_id": [[0-9]{2}\/[0-9]{2}\/[0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2}]
"random_no" : [0-9],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
class 2, subclass 1 (ClearCredit)
{
"register": [0-7],
"token_id"=[[0-9]{2}\/[0-9]{2}\/[0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2}]
"random_no" : [0-9],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
class 2, subclass 2 (SetTariffRate)
{
"tariff_rate": [0-65535],
"token_id"=[[0-9]{2}\/[0-9]{2}\/[0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2}]
"random_no" : [0-9],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
class 2, subclass 3-4 (Set1stSectionDecoderKey, Set2ndSectionDecoderKey)
{
"meter_primary_account_no": [600727[0-9]{12}] | [0000[0-9]{14}],
"new_vending_key": [[0-9a-f]{16}],
"new_supply_group_code": [[0-9]{6}],
"new_tariff_index": [[0-9]{2}],
"new_key_revision_no": [[1-9]{1}],
"new_key_type": [0-3],
"new_key_expiry_no": [0-255],
"new_meter_primary_account_no": [600727[0-9]{12}] | [0000[0-9]{14}],
"ro": [0-1],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
class 2, subclass 5 (ClearTamperCondition)
{
"pad" : 0,
"token_id": [[0-9]{2}\/[0-9]{2}\/[0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2}]
"random_no" : [0-9],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
class 2, subclass 6 (SetMaximumPhasePowerUnbalanceLimit)
{
"mppul": [0-65535],,
"token_id": [[0-9]{2}\/[0-9]{2}\/[0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2}]
"random_no" : [0-9],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
class 2, subclass 7 (SetWaterMeterFactor)
{
"wm_factor" :: [0-65535],,
"token_id": [[0-9]{2}\/[0-9]{2}\/[0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2}]
"random_no" : [0-9],
"config_ref": "[a-fA-F0-9\-]{1,}"
}
Response
Parameter Type
application/json
200 Successful token generation
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully generated tokens"
},
"data": {
"token": {
"ref": "739bb327-0a38-4edf-9c8f-0da2384abed1"
"token_no": "58971730332229211910",
"created_at": "2020-08-18T06:52:10Z"
},
...
]
}
}
405 Invalid Input
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid input KeyRevisionNo"
}
}
500 Internal server error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Internal Server Error. Error generating token. \
Please try again later"
}
}
GET
/v1/tokens?token-ref=[{ref}|token={token}]
Request
Parameter Type
text/plain
Body
{
token_ref={guidv4}
token=[0-9]{20}
Response
Parameter Type
application/json
Responses will be made dependent on the token type as shown in section 8.1
200 Successful token generation
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully obtained token(s) details"
},
"data": {
"token": {
"ref": "739bb327-0a38-4edf-9c8f-0da2384abed1"
"token_no": "58971730332229211910",
"created_at": "2020-08-18T06:52:10Z"
},
...
]
}
}
405 Invalid Input
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully obtained token(s) details"
}
}
500 Internal server error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Internal server error. Please try again."
}
}
/v1/user
Create a new user
Request
Parameter Type
application/json
Body
{
"first_name" : "John",
"last_name" : "Doe",
"username" : "username",
"password" : "password",
"phone_no" : "0700100100",
"email" : "info@email.com",
"image_url" : "https://s3.aws.com/avatar.png",
"activated" : "true"
}
Response
Parameter Type
application/json
200 Successfully created user
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully created user"
},
"data": {
"user_ref": "5774a10f60414b67f12abb105235479e"
}
}
405 Invalid input
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid phone no"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/user
Get user
Request
Parameter Type
application/json
Response
Parameter Type
application/json
200 Successfully obtained user
{
"status": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully obtained user details",
"details": {
"user": {
"username": "username",
"first_name": "John",
"last_name": "Doe",
"phone_no": "0700100100",
"email": "info@email.com",
"image_url": "https:\/\/s3.aws.com",
"ref": "865d1cf67ffcd853",
"created_at": "2019-05-17 06:04:33",
"updated_at": "2019-05-17 06:04:33"
}
}
}
405 Invalid username
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid username"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/user
Update user details
Request
Parameter Type
application/json
Body
{
"ref" : "1f4f8c059071deab",
"first_name" : "Mary",
"last_name" : "Jane",
"username" : "mary",
"password" : "passwords",
"phone_no" : "0700100102",
"email" : "info@mary.com",
"image_url" : "https://s3.awss.com"
}
Response
Parameter Type
application/json
200 Successfully updated user
{
"status": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully updated user"
}
405 Invalid user details
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid user details"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/user
Delete user details
Request
Parameter Type
application/json
Response
Parameter Type
application/json
200 Successfully updated user
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully deleted user"
}
}
405 Invalid user reference
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid user ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/credentials
Get Credentials details
Request
Parameter Type
application/json
Body
"ref" : "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully obtained credentials
{
"status":
{
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Obtained permissions"
}
"details": {
"credentials": {
"key": "deccf75f6e941e95df6073497214c266",
"secret": "0367a85eb3859cf8e5de1683e5306bdb",
"activated": true,
"ref": "e28a730e37c35bc2",
"permissions": [
{
"ref": "b74a53d1356be68a",
"name": "Create Credentials",
"identifier": "create_credentials",
"notes": "Permission to create credentials",
"identifier": "create_credentials"
},
...]
}
]
}
405 Invalid credentials ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid credentials ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/credentials/?ref={ref}
Activate credentials
Request
Parameter Type
application/json
Body
"ref" = "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully obtained credentials
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully activated credentials"
}
405 Invalid credentials ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid credentials ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/credentials/?ref={ref}
Deactivate credentials
Request
Parameter Type
application/json
Body
"ref" = "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully deactivated credentials
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully deactivated credentials"
}
405 Invalid credentials ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid credentials ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/configurations
Get Configurations details
Request
Parameter Type
application/json
Body
"ref" : "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully obtained configurations
{
"status":
{
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Obtained configurations"
}
"details": {
"configuration": {
"key": "deccf75f6e941e95df6073497214c266",
"secret": "0367a85eb3859cf8e5de1683e5306bdb",
"activated": true,
"ref": "e28a730e37c35bc2"
}
]
}
405 Invalid credentials ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid configurations ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/configurations/?ref={ref}
Activate configurations
Request
Parameter Type
application/json
Body
"ref" = "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully obtained configuration
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully activated configuration"
}
405 Invalid configuration ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid configuration ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/configuration/?ref={ref}
Deactivate configuration
Request
Parameter Type
application/json
Body
"ref" = "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully deactivated configuration
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully deactivated configuration"
}
405 Invalid configurations ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid configuration ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/credits
Get Credits details
Request
Parameter Type
application/json
Response
Parameter Type
application/json
200 Successfully obtained credits
{
"status":
{
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Obtained credits"
}
"data": {
"credits": {
"ref": "deccf75f6e941e95df6073497214c266",
"value": "100",
"currency": "KES",
"units": "100",
"purchase_date": "2020-11-30T16:34:36.302Z",
"user_ref": "50....3867"
}
]
}
405 Invalid credits ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid credits ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/transactions
Get Credits and Transaction details
Request
Parameter Type
application/json
Response
Parameter Type
application/json
200 Successfully obtained credits
{
"status":
{
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Obtained credits"
}
"data": {
"credits": {
"ref": "deccf75f6e941e95df6073497214c266",
"value": "100",
"currency": "KES",
"units": "100",
"purchase_date": "2020-11-30T16:34:36.302Z",
"user_ref": "50....3867"
},
"purchase": {},
"consumption": {}
]
}
405 Invalid credits ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid credits ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/public-key
Get Public Keys
Parameter Type
application/json
Body
"activated" = "[true|false]"
Response
Parameter Type
application/json
200 Successfully obtained public keys
{
"status":
{
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Obtained public keys"
}
"data": {
"data": [{
"key": "deccf75f...6073497214c266",
"name": "public key name",
"activated": true,
"ref": "e28a730e37c35bc2",
"user_ref": "e28a730e37c35bc2",
"created_at": "2020-11-30T16:34:36.302Z",
}
]
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/public-key
Add Public Key
Request
Parameter Type
application/json
Body
{
"name": "public key",
"user_ref": "ead45..89ecde",
"public_key": "MhIl….qWq==",
"activated": "false"
}
Response
Parameter Type
application/json
200 Successfully created public keys
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully created public key"
},
"data": {
"public_key": "MhIl….qWq==",,
"activated": "true",
"ref": "c0e22...dc67677",
"user_ref": "e221d...7677",
"created_at": "Successfully created public key"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/public-key
Activate public keys
Request
Parameter Type
application/json
Body
"ref" = "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully deactivated public key
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully activated public key"
}
405 Invalid public key ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid public key ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
/v1/public-key
Deactivate public keys
Request
Parameter Type
application/json
Body
"ref" = "b74a53d1356be68a"
Response
Parameter Type
application/json
200 Successfully deactivated public key
{
"status": {
"code": 200,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Successfully deactivated public key"
}
405 Invalid public key ref
{
"status": {
"code": 405,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid public key ref"
}
}
500 Internal Server Error
{
"status": {
"code": 500,
"request_id": "926c4e5e-6d22-410f-8b56-44f58f383a05",
"message": "Invalid server error"
}
}
