Overview

This guide gives step by step instructions on how you can integrate miniOrange Group APIs with your system.

Table Of Contents

  • Step 1: Create Authentication Header
  • Step 2: API Details

Pre-requisites

  • You need to create a free trial account with miniOrange.
  • Login to miniOrange console and Click on the Settings provided on the right top corner of the console.
  • Copy your Api Key and follow the steps below to generate the Authentication Header.

Step 1: Create Authentication Header

To be able to call our challenge and validate Rest APIs, you will need to set the authorization headers required to make sure that the request being made is by a valid user. You can check the sample JAVA and PHP code below to get an idea on how you can create the authorization headers.

The following values need to be set in the Header of the HTTP Request being made.

Attribute Description
Customer-Key Your customer key.
Api-Key Your Api Key
Timestamp The time in milliseconds when the request is being made
Authorization Sha 512 Hash Value consisting of the customer key , current timestamp and api key.

You can get your Customer-Key and Api Key by following these steps:

  • Log in to your Admin Dashboard.
  • Go to System Settings from the top right corner. You will find all of your information under the Account Details section.

Sample Code

  • Java
  • PHP
        /* You can get customer Key and customer Api Key from your admin dashboard */
        String customerKey = "<YOUR_CUSTOMER_KEY>";
        String apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
        /* Creating the Hash using SHA-512 algorithm (Apache Shiro library) */
        String stringToHash = customerKey + currentTimeInMillis + apiKey;
        String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
        HttpPost postRequest = new HttpPost("<URL for calling API>");
        /* Setting the Authorization Header values */
        postRequest.setHeader("Customer-Key", customerKey);
        postRequest.setHeader("Timestamp", currentTimeInMillis);
        postRequest.setHeader("Authorization", hashValue)
        /* You can get customer Key and customer Api Key from your admin dashboard*/
        $customerKey = "<YOUR_CUSTOMER_KEY>";
        $apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        $currentTimeInMillis = round(microtime(true) * 1000);
        /* Creating the Hash using SHA-512 algorithm */
        $stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) . $apiKey;
        $hashValue = hash("sha512", $stringToHash);
        /* Add $customerKeyHeader,$timestampHeader and $authorizationHeader in the httpheader */
        $customerKeyHeader = "Customer-Key: " . $customerKey;
        $timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', '' );
        $authorizationHeader = "Authorization: " . $hashValue;

Step 2: API Details

Get All Groups

To get all groups, you need to make a HTTP POST request to our get all groups API. Our Get All Groups API accepts the JSON input.

Method POST
URL https://login.xecurify.com/moas/api/admin/groups/getall

Request headers:

Parameters Type
Content-Type application/json
Customer-Key int
Timestamp int
Authorization String

Customer­Key: Customer­Key​ is the customer key for your account and must be sent with all client requests.

Timestamp: Timestamp​ specifies current time in milliseconds e.g 1474522813982.

Authorization: Authorization​ specifies SHA 512 hash value of string concatenated with customerKey, time in milliseconds and api key for your account e.g sha512(customerKey + timeInMillis + apiKey).

A sample code for generating the headers using this information can be found in the next section below.

Sample Code for Request Headers:

In the following code, just replace <YOUR_CUSTOMER_KEY> and <YOUR_API_KEY> with the values from the above table.

  • Java
  • PHP
        /* The customer Key provided to you */
        String customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        String apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
        /* Creating the Hash using SHA-512 algorithm (Apache Shiro library) */
        String stringToHash = customerKey + currentTimeInMillis + apiKey;
        String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
        HttpPost postRequest = new HttpPost("<URL for calling API>");
        /* Setting the Authorization Header values */
        postRequest.setHeader("Customer-Key", customerKey);
        postRequest.setHeader("Timestamp", currentTimeInMillis);
        postRequest.setHeader("Authorization", hashValue)
        /* The customer Key provided to you */
        $customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        $apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        $currentTimeInMillis = round(microtime(true) * 1000);
        /* Creating the Hash using SHA-512 algorithm */
        $stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) . $apiKey;
        $hashValue = hash("sha512", $stringToHash);
        $customerKeyHeader = "Customer-Key: " . $customerKey;
        $timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', '' );
        $authorizationHeader = "Authorization: " . $hashValue;
        /* Add $customerKeyHeader,$timestampHeader and $authorizationHeader in the httpheader */

Request Parameters:

Parameters Type
customerKey (required) int
batchSize (required) Int
batchNo (required) Int

Example Request body:


        {
            "customerKey" : "123",
            "batchSize" : 10,
            "batchNo" : 1


        }

Example Response:


        {
            "customerId":123,
            "status":"SUCCESS",
            "message":"Groups retrieved successfully.",
            "groups":[
            {"groupName":"DEFAULT",
            "customerId":123,
            "isDefault":true,
            "isCustomerDefault":true,
            "isUserInviteEnabled":false,
            "numOfUsersInGroup":14},
            {"groupName":"Test1",
            "customerId":123,
            "isDefault":false,
            "creationDttm":1589974809090,
            "lastUpdatedDttm":1589974809090,
            "isCustomerDefault":false,
            "isUserInviteEnabled":false,
            "numOfUsersInGroup":2}],
            "fetchedCount":2,
            "nextBatch":-1




        }

Update Group API

To update an existing Group, you need to make a HTTP POST request to our update group API. Our Update Group API accepts the JSON input.

Request

Method POST
URL https://login.xecurify.com/moas/api/admin/groups/update

Request headers:

Parameters Value
Content-Type application/json
Customer-Key int
Timestamp int
Authorization String

Customer­Key: Customer­Key​ is the customer key for your account and must be sent with all client requests.

Timestamp: Timestamp​ specifies current time in milliseconds e.g 1474522813982.

Authorization Authorization​ specifies SHA 512 hash value of string concatenated with customerKey, time in milliseconds and api key for your account e.g sha512(customerKey + timeInMillis + apiKey).

A sample code for generating the headers using this information can be found in the next section below.

Sample Code for Request Headers:

In the following code, just replace <YOUR_CUSTOMER_KEY> and <YOUR_API_KEY> with the values from the above table.

  • Java
  • PHP
        /* The customer Key provided to you */
        String customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        String apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since
        midnight, January 1, 1970 UTC. */
        String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
        /* Creating the Hash using
        SHA-512 algorithm (Apache Shiro library) */
        String stringToHash = customerKey + currentTimeInMillis + apiKey;
        String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
        HttpPost postRequest = new HttpPost("<URL for calling API>");
        /* Setting the Authorization Header values */
        postRequest.setHeader("Customer-Key", customerKey);
        postRequest.setHeader("Timestamp", currentTimeInMillis);
        postRequest.setHeader("Authorization", hashValue)
        /* The customer Key provided to you */
        $customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        $apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        $currentTimeInMillis = round(microtime(true) * 1000);
        /* Creating the Hash using SHA-512 algorithm */
        $stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) . $apiKey;
        $hashValue = hash("sha512", $stringToHash);
        $customerKeyHeader = "Customer-Key: " . $customerKey;
        $timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', '' );
        $authorizationHeader = "Authorization: " . $hashValue;
        /* Add $customerKeyHeader,$timestampHeader and $authorizationHeader in the httpheader */

Request Parameters :

Parameters Type
customerKey (required) int
groups (required) ArrayList

Attributes in groups Arraylist :

Parameters Type
groupName (required) String
isDefault (required) String (true or false)
groupAttribute1 String
groupAttribute2 String
……… String
groupAttribute50 String

Example Request Body


        {
            "customerKey": 123,
            "groups": [{
            "groupName": "TestGroup",
            "customerId": "123",
            "isDefault": "true",
            "groupAttribute1": "TestAttribute1"}]





        }

Example Response


        {
            "customerId":123,
            "status":"SUCCESS",
            "message":"Groups updated successfully."




        }

Update Members API

To add or remove users to a group, you need to make a HTTP POST request to our update member API. Our Update Member API accepts the JSON input.

Request:

Method POST
URL https://login.xecurify.com/moas/api/admin/groups/members/update

Request headers:

Parameters Values
Content-Type application/json
Customer-Key int
Timestamp int
Authorization String

Customer­Key: Customer­Key​ is the customer key for your account and must be sent with all client requests.

Timestamp: Timestamp​ specifies current time in milliseconds e.g 1474522813982.

Authorization: Authorization​ specifies SHA 512 hash value of string concatenated with customerKey, time in milliseconds and api key for your account e.g sha512(customerKey + timeInMillis + apiKey).

A sample code for generating the headers using this information can be found in the next section below.

Sample Code for Request Headers:

In the following code, just replace <YOUR_CUSTOMER_KEY> and <YOUR_API_KEY> with the values from the above table.

  • Java
  • PHP
        /* The customer Key provided to you */
        String customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        String apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since
        midnight, January 1, 1970 UTC. */
        String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
        /* Creating the Hash using
        SHA-512 algorithm (Apache Shiro library) */
        String stringToHash = customerKey + currentTimeInMillis + apiKey;
        String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
        HttpPost postRequest = new HttpPost("<URL for calling API>");
        /* Setting the Authorization Header values */
        postRequest.setHeader("Customer-Key", customerKey);
        postRequest.setHeader("Timestamp", currentTimeInMillis);
        postRequest.setHeader("Authorization", hashValue)
        /* The customer Key provided to you */
        $customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        $apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        $currentTimeInMillis = round(microtime(true) * 1000);
        /* Creating the Hash using SHA-512 algorithm */
        $stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) . $apiKey;
        $hashValue = hash("sha512", $stringToHash);
        $customerKeyHeader = "Customer-Key: " . $customerKey;
        $timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', '' );
        $authorizationHeader = "Authorization: " . $hashValue;
        /* Add $customerKeyHeader,$timestampHeader and $authorizationHeader in the httpheader */

Request Parameters :

Parameters Type
customerKey (required) int
groupName (required) String
Users (required) ArrayList

Attributes in Users Arraylist :

Parameters Type
action String (remove - (required while removing user from group,no need to send this attribute while adding users to group))
primaryEmail (required) String

Example Request Body

        {
            "customerKey": 123,
            "groupName" : "testgroup1",
            "users" : [
            {"primaryEmail" : "demo1@miniorange.in"},
            {"primaryEmail" : "demo@miniorange.in"},
            {"primaryEmail" : "demouser@miniorange.in","action" : "remove"}
                    ]


        }

Example Response

        {
            "customerId":123,
            "status":"SUCCESS",
            "message":"Groups updated successfully."



        }

Get All User-Group Mappings API

To get all users from Custom Groups, you need to make a HTTP POST request to our user-group mapping API. Our User Group Mapping API accepts the JSON input.

Request:

Method POST
URL https://login.xecurify.com/moas/api/admin/groups/members

Request headers:

Parameters Values
Content-Type application/json
Customer-Key int
Timestamp int
Authorization String

Customer­Key: Customer­Key​ is the customer key for your account and must be sent with all client requests.

Timestamp: Timestamp​ specifies current time in milliseconds e.g 1474522813982.

Authorization Authorization​ specifies SHA 512 hash value of string concatenated with customerKey, time in milliseconds and api key for your account e.g sha512(customerKey + timeInMillis + apiKey).

A sample code for generating the headers using this information can be found in the next section below.

Sample Code for Request Headers:

In the following code, just replace <YOUR_CUSTOMER_KEY> and <YOUR_API_KEY> with the values from the above table.

  • Java
  • PHP
        /* The customer Key provided to you */
        String customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        String apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since
        midnight, January 1, 1970 UTC. */
        String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
        /* Creating the Hash using
        SHA-512 algorithm (Apache Shiro library) */
        String stringToHash = customerKey + currentTimeInMillis + apiKey;
        String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
        HttpPost postRequest = new HttpPost("<URL for calling API>");
        /* Setting the Authorization Header values */
        postRequest.setHeader("Customer-Key", customerKey);
        postRequest.setHeader("Timestamp", currentTimeInMillis);
        postRequest.setHeader("Authorization", hashValue)
      /* The customer Key provided to you */
        $customerKey = "<YOUR_CUSTOMER_KEY>";
        /* The customer API Key provided to you */
        $apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        $currentTimeInMillis = round(microtime(true) * 1000);
        /* Creating the Hash using SHA-512 algorithm */
        $stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) . $apiKey;
        $hashValue = hash("sha512", $stringToHash);
        $customerKeyHeader = "Customer-Key: " . $customerKey;
        $timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', '' );
        $authorizationHeader = "Authorization: " . $hashValue;
        /* Add $customerKeyHeader,$timestampHeader and $authorizationHeader in the httpheader */

Request Parameters :

Parameters Type
customerKey (required) int
batchSize (required) int
batchNo (required) int

Example Request Body

        {
            "customerKey" : 123,
            "batchSize" : 100,
            "batchNo" : 1



        }

Example Response

        {
            "customerId":123,
            "status":"SUCCESS",
            "message":"Groups retrieved successfully.",
            "groupDetails":[
            {"primaryEmail":"demouser1@miniorange.in","creationDttm":1589974809092,"lastUpdatedDttm":1589974809092,"groupName":"TestGroup1"},
            {"primaryEmail":"demouser2@miniorange.in","creationDttm":1589974835484,"lastUpdatedDttm":1589974835484,"groupName":"TestGroup1"},
            {"primaryEmail":"demouser1@miniorange.in","creationDttm":1584345818550,"lastUpdatedDttm":1584345818550,"groupName":" TestGroup2"},
            {"primaryEmail":"demouser2@miniorange.in","creationDttm":1584345868973,"lastUpdatedDttm":1584345868973,"groupName":" TestGroup2"}],
            "fetchedCount":4,
            "nextBatch":-1




        }