Getting Started with Mend SCA API 2.0

The Mend API 2.0 is a REST-compliant API that enables the automation of workflows in a REST-compliant format. The API features:

Access for any user with Mend credentials, via a user key, is available on the user's profile page in the Mend App.
Improved security with a JWT token per organization, which expires every 30 minutes.
Added scalability with support for pagination, filtering, and sorting search results.
Broader functionality is available programmatically.
API documentation in standard REST format for easy navigation and search.

Note: If you have a dedicated instance of Mend, contact your Mend representative to access this API on your instance.

Start Using SCA API 2.0 with Postman

The easiest way to get started with the SCA API 2.0 is to use it inside an API Platform tool like Postman.

Download the API’s definition in JSON format.
Select all the text (in JSON format) and copy.
Open Postman
Select Import
A new window will pop up. Paste the definition into Postman:
Select Postman Collection, then click on Import:
Find and copy your base URL from the Mend SCA App → Integrate → Organization → API Base URL (v2.0). The format of the URL is:
1. For Mend instances: https://api-<instance>.mend.io
2. For WhiteSource instances: https://api-<instance>.whitesourcesoftware.com
Insert this URL as the {{baseUrl}} environment variable in Postman. You can set this in your Collection-level variables, Globals, or use a separate, dedicated environment for the Mend API and create the {{baseUrl}} environment variable there:

Log into SCA API 2.0

You must have a valid Mend user to log in to an organization to use the API endpoints. Use the login endpoint and add:

Your email address associated with your Mend user (Mend SCA App → Profile → Identity)
Your organization token (Mend SCA App → Integrate → Organization → API Key)
Your Mend user key (Mend SCA App → Profile → User Keys)

Tip: Set the credentials above for the login endpoint using Postman environment variables. For example:

CODE

{
  "email": "{{email}}",
  "orgToken": "{{apiKey}}",
  "userKey": "{{userKey}}"
}

The response returns the orgUuid and a JWT token which is valid until it expires (30 minutes), for that organization only. For subsequent API calls, you must use your JWT token as your authenticated entry into the API, in conjunction with either the orgUuid or the orgToken.

Note: Once logged in, if you need access to a different organization, you can use the Change Organization API Call.

Authenticate API 2.0 Calls in Postman

After login, you will need to use the jwtToken provided to authenticate the API call for the specific organization. Each API call may require certain path variables, such as orgToken or productToken, depending on things such as the hierarchy level, report configuration requirements, etc.

Let’s use the Get Organization Users call as an example. To add the jwtToken to the call in Postman:

Select the Authorization tab and select Bearer Token.
Place the jwtToken value provided earlier into the Token setting:
Save your changes.

Tip: For step 2, you can keep the Authorization Type as “Inherit auth from parent” and run a Postman Test after calling the login endpoint to automate the creation of Postman environment variables for your JWT Token value. For example:

CODE

let responseData = pm.response.json();

// Set JWT Token Environment Variable
var responseToken = responseData["retVal"]["jwtToken"];
pm.environment.set("jwtToken", responseToken);

Continuing with our Get Organization Users call example, you will also need to set your orgTokenin the Path Variables. To do so:

Select the Params tab.
Under Path Variables, find the orgToken Key and input your orgUuid received during login into the Value setting (Note: You can also set this as an environment variable):
Save your changes.

Note: If you get Error 401 Unauthorized, it's because you forgot to add the bearer token or are accessing the wrong organization.

Pagination and Sorting for Large Results

For large results, the API’s scalability allows:

Pagination by default at every 50 results, where the first page is page 0. You can change the size of the page by editing pageSize and specifying the page number to retrieve using the page. The maximum value for pageSize is 10,000.
Filter the results with the search parameter to reduce the large results set to gain even greater efficiencies. The documentation of each endpoint describes the fields which can be filtered.
Sort by different fields in the results using the sort parameter, so that your desired item is higher up the list, saving time and resources when automating tasks. The documentation of each endpoint describes the fields which can be filtered.

With pagination, API responses contain information on the resulting output via the additionalData block:

totalItems: The total count of data points returned in an API response.
isLastPage: Defines whether the current page represents the conclusion of the API response. When “true”, this signifies you are viewing the last page of the API response. When “false”, this indicates there are further pages remaining.

For example:

CODE

{
    "additionalData": {
        "totalItems": 367,
        "isLastPage": false
    }

Typical API Workflow

Typically you would call the API log-in to get your JWT bearer token, then call another API to get a list of items to cycle through, and then call a third API to extract specific details you need for one or all your items. For example, if you want to get alerts for a specific product, you would:

Login (call to login) to your org (if needed, if you had a 401 error).
Use the bearer token (jwtToken) to get organization entities (call to entities) to get a list of projects within the list of products.
For a specific product id, get a list of alerts (alerts/security).