API Basics

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

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:

BASE_URL/api/API_VERSION/json/API_LOGIN/GMT_UNIXTIME/SIGNATURE

Headers

All API calls require the following headers:

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

BASE_URL

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://TENANT_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.

GMT_UNIXTIME

Unix timestamp 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 SHA hash of the Unix timestamp, your API secret, and the request body concatenated with a + symbol.

Hex ( SHA_HASH (gmtUnixTime + API Secret + Request Body + API Secret) )

The following algorithms can be used to encrypt your requests:

• SHA-1
• SHA-224
• SHA-256
• SHA-384
• SHA-512

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": [{
               "conv_id": {processID},
               "type": "create",
               "obj": "task",
               "data": {
                    "param": 1
               }
          }]
}

2. Concatenate all of the required values:

1624614902 + hNThdrdYYWKm7om8zNURRppAnh0Cod3anp7JsiCmNWPM8p56tv + {"timeout": 30,"ops": [{"conv_id": {processID},"type": "create","obj": "task","data": {"param": 1}}]} + hNThdrdYYWKm7om8zNURRppAnh0Cod3anp7JsiCmNWPM8p56tv

3. Hash the result using SHA-1 (or one of the other Secure Hash Algorithms that MPO supports), yielding:

e27118f58c22f410b360d8122a6f3df42d5a5e42

4. 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, unixTime, signature, apiSecret and processID.

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"
          }]
}

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 a user with administrator access.
2. Go to the Users & Groups tab.
3. Select 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 a user with administrator access.
2. Go to the Users & Groups tab.
3. Go to the API keys section.
4. Select 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 select the copy icon in the third column.

Creating API keys using the API

You can create API keys using the following URL template:

BASE_URL.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"
          }],
          "company_id": "i123456789"
     }]
}

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
                    }]
               }]
     }]
}