API Basics

The Mambu Process Orchestrator (MPO) Remote Procedure Call API allows you to create and modify tasks, edit process logic, and manage users programatically.

We recommend using API v2 of the MPO API in most instances.

API Overview

The MPO API is a Remote Procedure Call (RPC) API that accepts JSON. Unless otherwise indicated, all requests use the HTTP POST operation, and the desired operation is specified in the request body in JSON. The API requires API keys, and each key has a name, a numeric API login and an API Secret.

Most calls to the MPO API use the following endpoint:

{BASEURL}/api/{API_VERSION}/json/{API_LOGIN}/{GMT_UNIXTIME}/{SIGNATURE}

Headers

All API calls require the following headers:

'Content-type: application/json; charset=utf8'

BASEURL

This URL is provided to you in the signup email. If your instance is in a shared environment the URL may look like this: https://ireland2.mpo.mambu.com/. If you have a dedicated environment the url may look like this: https://{COMPANY_NAME}.mpo.mambu.com/.

API_VERSION

Specify the MPO API version. Use 2 for API v2 and 1 for API v1. We recommend using API v2 of the MPO API in most instances.

API_LOGIN

Specify the API user who is accessing the API. You can find your API Login by going to Users & Groups > API keys in the MPO UI. Find your API user and copy the number in the second column, under Login.

Creating API keys in the MPO UI

GMT_UNIXTIME

Unix time stamp in seconds, such as 1631171468. This value must be generated at the time the request is issued. We recommend generating this value using a standard library, such as the JavaScript Moment library.

SIGNATURE

Signatures are used to authenticate requests. They are a hexadecimal representation of the SHA1 hash of the Unix timestamp, your API secret, and the request body concatenated with a + symbol.

Hex ( SHA1(GMT_UNIXTIME + API Secret + Request Body + API Secret) )

For information on where to find your API secret, see API Secret in the Authentication section.

Example of generating signature

  1. In the following example, we are generating a signature for a request with the request body shown below, using the GMT_UNIXTIME value of 1624614902 and sample API secret value of hNThdrdYYWKm7om8zNURRppAnh0Cod3anp7JsiCmNWPM8p56tv.
{
    "timeout": 30,
        "ops": [
            {
                "processID": {processID},
                "type": "create",
                "obj": "task",
                "data": {
                "param": 1
            }
        }]
}
  1. Concatenate all of the required values:
1624614902 + hNThdrdYYWKm7om8zNURRppAnh0Cod3anp7JsiCmNWPM8p56tv + {"timeout": 30,"ops": [{"processID": {processID},"type": "create","obj": "task","data": {"param": 1}}]} + hNThdrdYYWKm7om8zNURRppAnh0Cod3anp7JsiCmNWPM8p56tv
  1. Hash the result using SHA1, yielding:

e27118f58c22f410b360d8122a6f3df42d5a5e42

  1. Convert the result to a hexadecimal value. This is your signature.

653237313138663538633232663431306233363064383132326136663364663432643561356534320a

Using a script to create a signature

We recommend using a pre-request script to create your signature programmatically.

You can create a signature using a pre-request function or script. Below is a sample JavaScript script that may be used as a pre-request script in Postman.

This script requires Postman to be configured with the environment variables apiSecret, processID, unixTime, and SIGNATURE, and apiSecret and processID must have valid values.

var moment = require('moment');
var unixtime = moment().unix();
var secret = pm.environment.get("apiSecret");
var procId = pm.environment.get("processID");

pm.environment.set("unixTime", unixtime);

var body = request.data;

body = body.replace(/{processID}/ig, procId);

var signature = CryptoJS.SHA1(unixtime + secret + body + secret);

pm.environment.set("SIGNATURE", CryptoJS.enc.Hex.stringify(signature));

Request Body

Depending on the request, the actual contents of your request body may differ greatly, but this example request for an API key shows the general structure:

{
  "ops": [
    {
      "type": "get",
      "obj": "chart",
      "obj_id": "5f3d452f82ba960c30188781",
      "params": [],
      "company_id": "i404856373",
      "id": "23242"
    }
  ]
}
ParameterTypeDescriptionRequired
opsJSON ObjectA list enclosing all the tasks to run on MPO.Yes
ops[].typestringThe type of task.Yes
ops[].objstringAn object type to run the tasks on.No
ops[].obj_idstringThe ID of the object.No
ops[].paramsstringA list of parameters or variables to pass to the task.No
ops[].company_idstringThe ID of the company.Yes
ops[].idstringAn ID that is echoed in the response to match a response to a request.No

Authentication

API keys allow you to authenticate API requests. An API secret is auto-generated when you create an API key, and may then be used to secure your requests. In most cases, you must also create a signature.

MPO does not support key rotation or expiration. For instructions on how to revoke API keys, see Revoking API Keys in the UI.



Creating API keys in the UI

  1. Log in with Admin user.
  2. Go to the Users & Groups tab.
  3. Click on Create > API keys in the top-right.
  4. Give your API key a title in the pop-up.
  5. Go to the API keys tab to get the API ID and to copy the API secret.

Revoking API keys in the UI

  1. Log in with Admin user.
  2. Go to the Users & Groups tab.
  3. Go to the API keys section.
  4. Click Remove next to the API keys you want to remove.

API secret

The API secret is provided when you create an API key. The API secret is a required part of a signature. You can find your API secret by going to Users & Groups > API keys in the MPO UI. Find your API user and click the copy icon in the third column.

Creating API keys using the API

You can create API keys using the following URL template:

{BASEURL}.mpo.mambu.com/api/2/json/{API_LOGIN}/{GMT_UNIXTIME}/{SIGNATURE}

With this request body:

{
 "ops": [
   {
     "type": "create",
     "obj": "user",
     "title": {API_KEY_NAME},
     "logins": [
       {
         "type": "api"
       }
     ],
   }
 ]
}
ParameterTypeDescriptionRequired
opsJSON ObjectA list enclosing all the tasks to run on MPO.Yes
ops[].typestringThe type of task. Must be create.Yes
ops[].objstringAn object type. Must be user.Yes
ops[].titlestringA name for the API KeyYes
ops[].loginsarrayA list enclosing the login type.Yes
ops[].logins[].typestringThe login type. In this case, api for the API key.Yes

Responses

The secret value is returned in the key field.

{
    "request_proc": "ok",
    "ops": [
        {
            "id": "",
            "obj": "user",
            "proc": "ok",
            "users": [
                {
                    "obj_id": 76332,
                    "title": "Here we go again",
                    "logins": [
                        {
                            "type": "api",
                            "key": "h4GSZNqPvkyi7L1IyyzMe8OtPj56xPX2rxNrbvaO6y20075ZPX",
                            "obj_id": 113135
                        }
                    ]
                }
            ]
        }
    ]
}
parameterdescription
request_procReturns ok if all the tasks ran successfully or errors if otherwise.
opsA list enclosing responses from all of the tasks run on MPO.
ops[].idA request ID.
ops[].procReturns ok if a particular task runs successfully or errors if otherwise.
ops[].objAn object type. Usually user.
ops[].usersA list of users created by the request.
ops[].users[].obj_idThe ID of the API key.
ops[].users[].titleThe name of the API key.
ops[].users[].loginsA list of the details of the API key.
ops[].users[].logins[].typeThe login type. Will return api for API keys.
ops[].users[].logins[].keyThe API key’s secret.
ops[].users[].logins[].obj_idAn ID of API key login.