JSON API

The JSON API allows you to interact with Joget's platform by accessing data and integrating external systems. This guide provides basic steps and examples to help you get started quickly.

JSON API Authentication

Authenticate by Passing Parameters

• j_username
• j_password
• hash

Example:

Assuming the username and password required is "user1" and "password1" respectively, we can post the username and password to the JSON API using following script.

curl --location --request POST --data 'j_username=user1&j_password=password1' 'http://localhost:8080/jw/web/json/workflow/assignment/list'

{"total" : 12 }

If you prefer to use a hashed password, you can use the following script.

curl --location --request POST --data 'j_username=user1&hash=D012B772672A55A0B561EAA53CA7734E' 'http://localhost:8080/jw/web/json/workflow/assignment/list/pending'

{"total" : 12 }

Master Login Username and Password

When authentication using parameters, you are allowed to using a Master Credential to login as other user to performance workflow activities. 

To use it, set a Master Login Username and Master Login Password under System Settings > General Setting. By setting these values, a different user can be specified by passing in the "loginAs" parameter.

Assuming the master login username and master login password is "master" and "master" respectively, the master login hash will be "E505CF727D214A68CB03DA25DA978500".

The following example showcases how to use a Master Credential to login as "user1".

curl --location --request POST --data 'j_username=master&j_password=master&loginAs=user1' 'http://localhost:8080/jw/web/json/workflow/assignment/list'

{"total" : 12 }

Using master login hash:

curl --location --request POST --data 'j_username=master&j_password=master&loginAs=user1' 'http://localhost:8080/jw/web/json/workflow/assignment/list'

{"total" : 12 }

Basic Http Authentication

Since V4, Joget supports Basic HTTP Authentication in JSON API authentication so you can pass the credentials in the header.

Example:

Assuming the username and password required is "user1" and "password1" respectively, we can set the Basic Auth header to the JSON API using following script. 

curl --location --request POST 'http://localhost:8080/jw/web/json/workflow/assignment/list/pending' --header 'Authorization: Basic dXNlcjE6cGFzc3dvcmQx'

{"total" : 12 }

Hashed Password

Description

• Used in JSON API authentication and JavaScript Single Sign ON (SSO)

• Prevents a user's password from being directly exposed during authentication

• This Hashed Password method is only supported by Joget Internal Directory Manager.

Formula

md5(username + "::" + md5Base16(password));

E.g.: Assuming that the username is “admin” and the password is “admin”, the resulting hash should be “14ACD782DCFEB2BCDE2B271CCD559477”.

Sample Code (Java)

public static String md5(String content) {
    try {
        MessageDigest m = MessageDigest.getInstance("MD5");
        byte[] data = content.getBytes();
        m.update(data, 0, data.length);
        BigInteger i = new BigInteger(1, m.digest());
        return String.format("%1$032X", i);
    } catch (Exception ex) {}
    return "";
}
 
public static String md5Base16(String content) {
    try {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] bytes = md.digest(content.getBytes());
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < bytes.length; i++) {
            byte b = bytes[i];
            String hex = Integer.toHexString((int) 0x00FF & b);
            if (hex.length() == 1) {
                sb.append("0");
            }
            sb.append(hex);
        }
        return sb.toString();
    } catch (Exception e) {}
    return "";
}