Overview

miniOrange User APIs can be used to create/update/get users.

Pre-requisites

  • 1 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 and Copy your Api Key and add it in request headers.

1. Create User API

To create a user, you need to make a HTTP POST request to our create user API. Our Create User API accepts the JSON input.

Request

Method URL
POST The transaction ID for which request was generated.
status https://login.xecurify.com/moas/api/admin/users/create

Request Headers:

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

Customer­Key
Customer­Key​ is 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).

Sample Code for Request Headers:

  • 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 = "&lt;YOUR_CUSTOMER_KEY&gt;";
    /* The customer API Key provided to you */
    $apiKey = "&lt;YOUR_API_KEY&gt;";
    /* 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:

Params Type
customerKey (required) int
username (required) String
email (required) String
firstName (required) String
lastName (required) String
phone (optional) String
password (optional) String
groups (optional) ArrayList
alternateEmail (optional) String
customAttribute1 (optional) String
customAttribute2 (optional) ... String
customAttribute50 (optional) String

Example Request Body

    {
          "customerKey" : 116,
          "username" : "xyz123",
          "email" : "xyz@example.com",
          "firstName" : "john",
          "lastName" : "doe"
    }

Example Response

    {

      "userId" : 12345,
      "username" : "xyz123",
      "email" : "xyz@example.com",
      "status" : "SUCCESS",
      "message" : "End user created successfully."
    }

Example Java code for Request Body with Group Object

      JSONArray groupjsonarray = new JSONArray();
      String[] arr = {"test_group1","test_group2"};

      for(int i=0;i < arr.length;i++){
        JSONObject groupjson = new JSONObject();
        groupjson.put("name",arr[i]);
        groupjsonarray.add(groupjson);
      }


      Map<String,Object> map = new HashMap<String,Object>();

      map.put("customerKey",customerKey);
      map.put("username", "apitestuser");
      map.put("email", "xyz123@example.com");
      map.put("firstName","john");
      map.put("lastName","doe");
      map.put("groups",groupjsonarray);
      JSONObject json = new JSONObject();
      json.putAll( map );
      String jsonString = json.toJSONString();

      /* request json */

      {
        "customerKey" : 116,
        "username" : "xyz123",
        "email" : "xyz@example.com",
        "firstName" : "john",
        "lastName" : "doe",
        "groups":[{"name":"test_group1"},{"name":"test_group2"}]}
      }

2. Update User API

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

Request

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

Request Headers:

Same as above

Request Parameters:

Params Type
customerKey (required) int
username (required) String
email (required) String
firstName (required) String
lastName (required) String
phone (optional) String
password (optional) String
groups (optional) String
alternateEmail (optional) ArrayList
customAttribute1 (optional) String
customAttribute2 (optional) ... String
customAttribute50 (optional) String

Example Request Body

    {
      "customerKey" : 116,
      "username" : "xyz123",
      "email" : "abc@example.com",
      "firstName" : "john",
      "lastName" : "doe",
      "phone" : "+18888888888",
      "alternateEmail" : "abc@gmail.com"
    }

Example Response

    {
      "userId" : 12345,
      "username" : "xyz123",
      "email" : "xyz@example.com",
      "status" : "SUCCESS",
      "message" : "End User details are updated successfully."
    }

For updating group-membership against a user,you can optionally pass groups attribute in the API- Format to send groups object is shown below:

Request Parameters:

Params Type
name (required) String
attributes (optional) ArrayList (GroupAttributes is an arraylist of name:value of string type)

3. Get All Users API

To get all users, you need to make a HTTP POST request to our get user API. Our Get User API accepts the JSON input. Maximum 500 users allowed to fetch in single batch.

Request

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

Request Headers:

Same as above

Query Parameters:

Params Type
includePwdExpDttm boolean

Request Parameters:

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

Example Request Body

    {
      "customerKey" : 116,
      "batchSize" : 500,
      "batchNo" : 1
    }

Example Response

{
    "userId": 116,
    "guid": "add92ff0-4e34-4c3a-b37a-fb7b940ba3ab",
    "username": "testuser@gmail.com",
    "email": "testuser@gmail.com",
    "status": "SUCCESS",
    "message": "End User retrieved successfully.",
    "phone": "+1",
    "authType": "EMAIL",
    "users": [
    {
            "customerId": 123,
            "fname": "first name",
            "lname": "last name",
            "primaryPhone": "+1",
            "markForDeletion": false,
            "secondFactorAuthType": "EMAIL",
            "primaryEmail": "testuser@gmail.com",
            "idpEnabled": true,
            "creationDttm": "2024-01-09T06:45Z",
            "lastUpdatedDttm": "2024-01-09T08:19Z",
            "username": "testuser@gmail.com",
            "lastVerifiedDttm": 1704782703049,
            "phoneVerified": false,
            "emailVerified": false,
            "preferredLocale": "en",
            "isEnforce_2faOnNextLogin": false,
            "guid": "add92ff0-4e34-4c3a-b37a-fb7b940ba3ab",
            "sourceType": "Miniorange",
            "sourceIdentifier": "Admin: user@gmail.com",
            "passwordExpiryDate": "2024-02-17T05:30Z",  /* If query parameter "includePwdExpDttm=true" is added */
            "groups": [
                    "DEFAULT"
            ],
            "customAttributesAsList": [
                . . . . .
                . . . . .
            ]
                "customAttribute50":""
            }
               ],
        "fetchedCount":1,
        "nextBatch":2
    }

4. Get User API

To search and get a single user, you need to make a HTTP POST request to our get user API. Our Get User API accepts the JSON input.

Request

Method URL
POST https://login.xecurify.com/moas/api/admin/users/get

Request Headers:

Same as above

Query Parameters:

Params Type
includePwdExpDttm boolean

Request Parameters:

Params Type
customerKey (required) int
Username (required) String

Example Request Body

    {
      "customerKey" : 116,
      "username" : "john"
    }

Example Response

{
    "userId": 116,
    "guid": "add92ff0-4e34-4c3a-b37a-fb7b940ba3ab",
    "username": "testuser@gmail.com",
    "email": "testuser@gmail.com",
    "status": "SUCCESS",
    "message": "End User retrieved successfully.",
    "phone": "+1",
    "authType": "EMAIL",
    "users": [
    {
        "customerId": 123,
        "fname": "first name",
        "lname": "last name",
        "primaryPhone": "+1",
        "markForDeletion": false,
        "secondFactorAuthType": "EMAIL",
        "primaryEmail": "testuser@gmail.com",
        "idpEnabled": true,
        "creationDttm": "2024-01-09T06:45Z",
        "lastUpdatedDttm": "2024-01-09T08:19Z",
        "username": "testuser@gmail.com",
        "lastVerifiedDttm": 1704782703049,
        "phoneVerified": false,
        "emailVerified": false,
        "preferredLocale": "en",
        "isEnforce_2faOnNextLogin": false,
        "guid": "add92ff0-4e34-4c3a-b37a-fb7b940ba3ab",
        "sourceType": "Miniorange",
        "sourceIdentifier": "Admin: user@gmail.com",
        "passwordExpiryDate": "2024-02-17T05:30Z",  /* If query parameter "includePwdExpDttm=true" is added */
        "groups": [
                "DEFAULT"
        ],
        "customAttributesAsList": [
        . . . . .
        . . . . .
        ]
        "customAttribute50":""
        }
    ]
}

    /* If user not found */
    {
      "username":"abctest0",
      "status":"FAILED",
      "message":"Invalid username or email."
    }

5. Delete User API

To delete a single user, you need to make a HTTP POST request to our delete user API. Our Delete User API accepts the JSON input.

Request

Method URL
POST https://login.xecurify.com/moas/api/admin/users/delete

Request Headers:

Same as above

Request Parameters:

Params Type
customerKey (required) int
Username (required) String

Example Request Body

    {
      "customerKey" : 116,
      "username" : "john"
    }

Example Response

    {
       "customerId":123,
       "status":"SUCCESS",
       "message":"End User deleted successfully.",
    }

   /* If user not found or request json is incorrect*/
   {
       You are not authorized to perform this operation
   }

6. Disable User API

To disable a single user, you need to make a HTTP POST request to our disable user API. Our Disable User API accepts the JSON input.

Request

Method URL
POST https://login.xecurify.com/moas/api/admin/users/disable

Request Headers:

Same as above

Request Parameters:

Params Type
customerKey (required) int
Username (required) String

Example Request Body

    {
      "customerKey" : 116,
      "username" : "john"
    }

Note: you can pass any value in username field username or email to search the user if username and email are not same.

Example Response

HTTP/1.1 200 OK

    {
       "customerId":123,
       "status":"SUCCESS",
       "message":The end user is disabled.,
    }

/ If user not found/

HTTP/1.1 403 FORBIDDEN

Invalid username or email.

/ If header is incorrect /

HTTP/1.1 400 BAD REQUEST

API Authorization: API Request denied: Incorrect Authorization header.

7. Enable User API

To enable a single user, you need to make a HTTP POST request to our enable user API. Our Enable User API accepts the JSON input.

Request

Method URL
POST https://login.xecurify.com/moas/api/admin/users/enable

Request Headers:

Same as above

Request Parameters:

Params Type
customerKey (required) int
Username (required) String

Example Request Body

    {
      "customerKey" : 116,
      "username" : "john"
    }

Note: you can pass any value in username field username or email to search the user if username and email are not same.

Example Response

HTTP/1.1 200 OK

    {
       "customerId":123,
       "status":"SUCCESS",
       "message":User has been enabled successfully.,
    }

/ If user not found/

HTTP/1.1 403 FORBIDDEN

Invalid username or email.

/ If header is incorrect /

HTTP/1.1 400 BAD REQUEST

API Authorization: API Request denied: Incorrect Authorization header.

8. Fetch End User count API

To get the count of end users for a particular customer, you need to make a HTTP GET request to our Fetch End User count API. Our Fetch End User count API accepts the JSON input.

Request

Method URL
GET https://login.xecurify.com/moas/api/admin/users/stats/count

Request Headers

Same as above

Example Response

SUCCESS

    {
       {
            status: "SUCCESS",
            statusCode : 200,
            message: "Total End Users retrieved successfully.",
            data: {
            count: 5
            }
       }
    }

9. Change User Password API

To change the login password of the miniOrange user, you need to make a HTTP POST request to our disable user API. Our Disable User API accepts the JSON input.

Request

Method URL
POST https://login.xecurify.com/moas/api/admin/users/change-password

Request Headers:

Same as above

Request Parameters:

Params Type
customerKey (required) String
username (required) String
Password (required) String
oldPassword (required) String

Example Request Body

{
   "customerKey":"51935",
    "username": "demouser",
    "password": "Passw0rd.",
    "oldPassword": "user@123"

}

Example Response

{
    "customerId": 51935,
    "status": "SUCCESS",
    "message": "Your password has been successfully changed."
}
  1. When requested old and new passwords are one and the same.
{
    "customerId": 296568,
    "status": "ERROR",
    "message": "Your current password and new password can not be same. Try again with different password."
}
  1. When the requested old password is incorrect
{
    "customerId": 296568,
    "status":"ERROR",
    "message": "The old password you entered is incorrect. Please try again."
}
  1. When API key or CustomerKey in the header are incorrect
{
    "status":"error",
    "code": "401",
    "message": "API Request denied: Incorrect Authorization header."
}