Introduction to the Nectar API

reayn3Uncategorized

Please use this link to access the more recommended way to use the Nectar API to generate tokens for production systems https://nectar.software/blog/?p=93

Nectar API is a cloud-based, REST API that allows utilities and service providers to generate STS (IEC 62055-41:2018) tokens. This guide is aimed at developers who wish to use the Nectar API to generate tokens for the prepaid electricity, water and gas meters or want to gain a deeper understanding of the STS standard and how it is used for prepayment.

Prequisities

  • 35 minutes
  • A valid STS Configuration
  • git to clone the Nectar API SDKs
  • Postman, Insomnia, curl enabled terminal to run basic commands

Step 1: Create an account

To begin using the Nectar API, first create an account at https://portal.nectar.software/register. You will receive an email to the registered email address for you to confirm registration.


Step 2: Login to Nectar API

Using the created credentials, log into Nectar API and create a new set of credentials at https://portal.nectar.software/credentials. The new set of credentials must contain at minimum the Generate Token Permission. Once the credential is generated, it will have a ref, key and secret. The key and secret will be necessary to make further calls to the Nectar API.

Step 3: Create an STS configuration

To generate STS tokens, you will first need to create a 128 bit AES symmetric key and your 4096 bit RSA keys PKI private-public key pair. To generate the 128 bit AES symmetric key, simply generate a random 16 character string and store it in a txt file with any desired name. The following is an example of a valid symmetric key, saved as symmetric_key.txt. 

sve5GXjhk[~&J/-w

Please note that this key must be kept confidential.

To generate a PKI key pair, you may use websites such as https://www.devglan.com/online-tools/rsa-encryption-decryption or use the following commands

openssl genrsa -out private_key.pem 4096
openssl rsa -in private_key.pem -pubout > public_key.pub

This command will generate a public private key pair and store it in the desired location.

Step 4: Upload the generated public key

For the Nectar API to decrypt submitted STS configurations, you will need to upload the generated public key in your PKI key pair at https://portal.nectar.software/public-keys. Give your public key any desired descriptive name. Kindly note that Nectar API does not enforce uniqueness of the Public Key name.

To copy the public key, use the following command

xclip -sel clip < id_rsa.pub

Be sure to select the activated checkbox and trim the public key to remove the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- sections of the public key. The Nectar API will validate the public key.

Step 4: Procure Credits

Credits will need to be procured to generate tokens via the Nectar API endpoints (https://api.nectar.software) or via any of the Nectar API SDKs. To procure credits, simply select the Buy button on the left of the Nectar API portal.

Credits can be procured using MPESA. Other forms of payments are still being added to the platform. To reload using other payment modes, please write to info@nectar.software for more details.

Step 5: Generate an STS configuration

An STS configuration must be generated and its ref referenced in your API calls. Therefore, at least 1 STS configuration must be created for every account in the Nectar API. To generate an STS configuration, navigate to the configurations page at https://portal.nectar.software/configurations.

There are multiple ways to create and securely manage STS configurations using the Nectar API. These include via the use of the Nectar API portal, SDKs or via the Nectar API REST endpoints at https://api.nectar.software. Using all these channels, STS configurations are encrypted on the client before being transmitted to the Nectar API virtual HSM.

For the purposes of this guide, we will use Option 2: Fill in the STS configurations tab to fill in the STS configuration. The following are the STS configuration details required

  1. Key Expiry No (KEN)
  2. Encryption Algorithm (EA)
  3. Token Carrier Type (TCT)
  4. Decoder Key Type Generation Algorithm (DKGA)
  5. Tariff Index (TI)
  6. Key Revision No (KRN)
  7. Vending Key (VK)
  8. Supply Group Code (SGC)
  9. Key Type (KT)
  10. Base Date (BD)
  11. Issuer Identification No (IIN)

The Nectar API documentation at https://portal.nectar.software/docs shows the format required for each of these parameters. Any name can be provided for the configuration. The symmetric key generated in step 3 will be used here. Kindly note that your private key used here will not be transmitted to the Nectar API server but is only used to locally encrypt the payload. In addition, the text -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- must be removed from the private key for this step. To view the specific encryption steps of the STS configuration before submission to the Nectar API server, please review the Nectar API documentation.

Once the STS configuration is encrypted and transmitted to the cloud HSM, you are now ready to begin generating tokens.

Step 6: Generate Tokens

There are a number of ways to generate tokens using the Nectar API. These are

  1. Use a Nectar API SDK available here
  2. Make REST requests to the Nectar API at https://api.portal.nectar.software. Refer to the documentation at https://portal.nectar.software/docs for more details.
  3. Through the Nectar API portal itself using the Simulators page at https://portal.nectar.software/simulators and selecting the Token Generator option.

While option 3 above is the fastest, for purposes of this guide, we will use a Nectar API SDK (Option 1) to show how requests to the Nectar API can be integrated into any existing code base.

Below is an example of token generation code using the Nectar API Java SDK

public class NectarTest {

    private final String KEY = "a0...38453";
    private final String SECRET = "cf....fd7a";

    private Nectar nectar = new Nectar(KEY, SECRET);

    public static void main(String[] args) {
        try {
            NectarTest test = new NectarTest();
            Map<String, Object> params = new HashMap<>();
            params.put("class", "2");
            params.put("subclass", "7");
            params.put("token_id", "2018-05-16T07:29");
            params.put("wm_factor", "10");
            params.put("random_no", "9");
            params.put("is_stid", "false");
            params.put("drn", "47500150231");
            params.put("config_ref", "9f4e2....f620");
            params.put("debug", "false");

           Token generatedToken = nectar.getTokenFactory()
                .generateToken(params);
           System.out.println(String.format("Generate Token\n====================\n%s\n", generatedToken));
    }
}

This generates the following output

4:04:34 PM: Executing task 'NectarTest.main()'...

> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes

> Task :NectarTest.main()
Response Code : 200
Generate Token
====================
Token { ref: 8e886a29-3766-40a9-9bae-1543e465e355, token_no: 24260829498939505863, user_ref: 49bc59e5-b261-423d-9600-fd479a31aca5,token_type: SetWaterMeterFactor_27, meter_no: 47500150231, created_at: 2021-07-22T13:04:38.386491Z }

Important to note is that

  1. The KEY and SECRET used in the example Java refer to the KEY and SECRET assigned to the credentials.
  2. When putting together the params HashMap, the config_ref refers to an STS configuration ref.

That’s all folks!