> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scan Apps via API

It's commonly requested for mobile app R\&D teams to be able to scan new versions of their mobile apps programmatically as part of their continuous integration and delivery process.  Using OneTrust's **Integrations** module, the ability to **Scan Apps via API** unlocks the ability to scan new apps and rescan existing apps without having to login to OneTrust and upload the app file in the UI.  We support both **REST** and **FTP** approaches, depending on file size.

## How To Setup

The following is required to Scan Apps with Integrations.

1. [Create Integration workflow](#create-integration-workflow) in the OneTrust **Integrations** module.
2. [Decide and Implement your Integration Method](#decide-your-integration-method) and update the Integration workflow accordingly.
3. [Prepare for Testing](#prepare-for-testing) by collecting API endpoint and authentication credentials.
4. [Test the Workflow](#test-the-workflow) and work through integration process.
5. [Monitor logs](#monitor-logs) to confirm success or troubleshoot issues.

## Create Integration Workflow

1. On the Integrations menu, select **Gallery**.  The **Integration Gallery** screen appears.
2. Use the search to locate the **Generic** system tile.

![](https://files.readme.io/9d067e6-integrations-gallery.png)

3. Click the **Generic** system tile. The **Gallery Details** screen appears.
4. Click the **Add** button on the **Mobile: Mobile App Scan** workflow. The **Add Workflow Name** modal appears.

![](https://files.readme.io/23c047f-mobile-app-scan-integrations.png)

5. Complete the fields in the modal, then click the **Create** button. The **Workflow Builder** screen appears.

![](https://files.readme.io/bf05abc-add-workflow-name-details.png)

| Field              | Description                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Workflow Name      | Enter a unique name for this new connection.                                                                             |
| Select Credential  | Select **None**. The API call will use Client Credentials to authorize access to the given tenant for security purposes. |
| Notification Email | Enter the user email that should receive all notification alerts for this workflow.                                      |

6. Click the **Activate** button in top-right.

## Decide and Implement the Integration Method

Currently, there are 2 methods to implement and it mainly depends on file size.

* [REST API](#implement-via-rest) (using `form-data`, files sizes < 64MB only)
* [FTP](#implement-via-ftp)

## Implement via REST API

On creation of new App Scan workflow, it is setup for **REST API** using `form-data` by default.  If your application is < 64MB and prefer this approach, then please proceed to [Prepare for Testing](#prepare-for-testing) section.

> 📘
>
> If your application file is > 64 MB, you can skip this section and proceed to [FTP](#ftp) configuration instead.

## Implement via FTP

To complete an FTP setup, you'll need to complete 2 steps:

1. Update the Webhook Action `uploadType`to be `FTP` and provie `filePath` information
2. Add an Action to Download Files from your FTP location

### Update Webhook Action for FTP

1. In the **Workflow Builder** screen, click the **Edit** icon on the **Webhook Action**.
2. Select `JSON` for **Payload Type** and paste in the following JSON payload to **Sample**

```json JSON
{ 
	"uploadType": "FTP", 
	"filePath": "string_value", 
	"fileType": "ipa/apk", 
	"name": "application_name", 
	"os": "application_OS" 
} 

```

![](https://files.readme.io/7380f3a-update-webhook-action.png)

### Add Action to Download Files from FTP

1. In the **Workflow Builder** screen, click the `+` icon under the **Conditional** section before the POST call
2. Select **Download File(s) from FTP**

![](https://files.readme.io/e364968-download-files-from-ftp.png)

3. Select your FTP credentials and click **Next**
4. Add the path to your FTP file and click **Finish**
5. Edit the **POST Create New Application** by clicking the edit icon and then **Advanced View** button to expose the **Body**
6. Add the below Freemarker + JSON under **Body** section and click **Finish**

```json Freemarker + JSON
{  
	<#list 0..step.ftp_1.fileInfoList?size-1 as n>  
  "fileId": "${(step.ftp_1.fileInfoList[n].reference)!}",  
  "fileType": "${(event.payload.fileType)!}",  
  "name": "${(event.payload.name)!}",  
  "orgId": "${(event.userDetails.orgGroupId)!}",  
  "os":"${(event.payload.os)!}"  
  <#if step.ftp_1.fileInfoList?size-1 != n>,</#if>  
  </#list>  
}
```

## Prepare for Testing

1. [Copy the POST URL](#copy-the-post-url)
2. [Create OAuth 2.0 Client Credential](#create-oaut-20-client-credential)

### Copy the POST URL

1. In the **Workflow Builder** screen, click the **Edit** icon on the **Webhook Action**.
2. Click the **Copy** button to copy the **HTTP POST URL**.  Save this for later reference to use during the API call.

![](https://files.readme.io/da3ab58-copy-post-url-on-webhook-action.png)

### Create OAuth 2.0 Client Credential

You'll need to create an OAuth 2.0 Client Credential to authorize the API calls' access to the OneTrust application. This information will need to be provided when configuring the API calls' authentication requirements.  For more information, see [Managing OAuth 2.0 Client Credentials](https://developer.onetrust.com/onetrust/docs/managing-oauth-20-client-credentials).

1. In the OneTrust application, click the gear icon in the upper right-hand corner to access **Global Settings**.
2. On the Global Settings menu, select **Access Management > Client Credentials**. The Credentials screen appears.
3. Click the **Add** button. The **Client Credentials** section of the **Add Client Credential** screen appears.
4. In the **Name** field, enter a name for the client credential.  Please note the **Name** will not be able to be modified after creation.
5. Optional: In the **Description** field, enter a description for the client credential.
6. In the **Access Token Lifetime** field, select the amount of time that should pass before the access token expires. The following options are available:

| Access Token Lifetime options |
| ----------------------------- |
| 1 Hour                        |
| 1 Day                         |
| 1 Week                        |
| 1 Month                       |
| 1 Year                        |

7. Click the **Next** button. The **Scope** section appears.
8. Enable **ALL** for the **Integration Scope** AND the **Cookie Scope**.
9. Click the **Create** button. The **Client ID and Secret** section appears.
10. In the **Download Credential** field, click the **Download** button. A `.txt` file containing the Client ID and Client Secret details will download to your local system.
11. Click the **Close** button.

## Test the Workflow

1. [Setup the API call to OneTrust Webhook](#setup-api-call-to-onetrust-webhook)
2. [Test a New App Scan](#test-a-new-app-scan)
3. [Test Rescan of App](#test-rescan-of-app)

### Setup the API Call to OneTrust Webhook

#### General

|              |                               |
| ------------ | ----------------------------- |
| Request Type | POST                          |
| Request URL  | POST URL copied from Workflow |

#### Authorization

|                       |                                                                |
| --------------------- | -------------------------------------------------------------- |
| Type                  | OAuth 2.0                                                      |
| Grant Type            | Client Credentials                                             |
| Access Token URL      | <https://{environment}.onetrust.com/api/access/v1/oauth/token> |
| Client ID             | From OT OAuth 2.0 credential                                   |
| Client Secret         | From OT OAuth 2.0 credential                                   |
| Client Authentication | Send as Basic Auth Header                                      |
| Access Token          | generated by provision of the above requirements               |

#### Headers

|              |                  |
| ------------ | ---------------- |
| Content-Type | application/json |

#### Body

|                   |                                                         |
| ----------------- | ------------------------------------------------------- |
| Body Type         | form-data                                               |
| Key: `file`       | .ipa \| .apk                                            |
| Key: `dataFields` | Applicable JSON based on New Scan or Rescan (see below) |

### Test a New App Scan

1. Ensure the necessary authentication parameters and headers are provided to connect with your given OneTrust environment.
2. In your developer tool, create a **POST** call and paste the **HTTP POST URL** copied from the **Webhook Trigger** action in the OneTrust application.
3. In the **Body**, select a package file (e.g. `.ipa` or `.apk`) for the **Value** of the field **Key**. File upload limit is 64MB.
4. In the **Body**, provide the following  JSON as the **Value** of the `dataFields` **Key**.

```json
// name:		Enter your new app's name
// platform:	Choose a platform according to your file type

{
	"name": "App Name", 
	"platform": "IOS" //input IOS or ANDROID based on app platform. Must be capitalized
}
```

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/4f4c13f2df7023cd1db41757a0177187aa0abc36b9eb65336a1e6bc6fb043e48-image_2.png",
        "",
        ""
      ],
      "align": "center"
    }
  ]
}
[/block]

4. Send the call. Upon a successful response (202), you should receive a **request ID**. This will be the corresponding string found in the workflow log.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/5dbddf1ae49e15e684092e21797ed9a4e7ed279820a90119273b3c6ca20fe0e7-image_3.png",
        "",
        ""
      ],
      "align": "center"
    }
  ]
}
[/block]

5. For information on how to view your scan results, see [Viewing and Categorizing Scan Results](https://developer.onetrust.com/onetrust/docs/view-and-categorize-scan-results).

*The mobile app Production ID can be found in the Instructions tab on the SDK screen.*

### Test Rescan of App

1. Ensure the necessary authentication parameters and headers are provided to connect with your given OneTrust environment.
2. In your developer tool, create a **POST** call and paste the **HTTP POST URL** from the **Webhook Trigger** action in the OneTrust application.
3. In the **Body**, select the new package file. (e.g. .ipa or .apk) for the **Value** of the field **Key**.
4. In the **Body**, provide the following JSON as the **Value** of the `dataFields` **Key**.

```json
// appId:		Provide your mobile app's ID,
// platform:	Choose a platform according to app type

{
	"appId": "app ID for which you want to rescan", 
	"platform": "ANDROID" 
}
```

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/f42c5a44a3d891e8210d86f92aed6ebbe3ba8c7571fd230c08414c2c3dbda122-image-20251203-143458.png",
        "",
        ""
      ],
      "align": "center"
    }
  ]
}
[/block]

*The mobile app Production ID can be found in the Instructions tab on the SDK screen.*

5. Send the call. Upon a successful response (202), you should receive a **request ID**. This will be the corresponding string found in the workflow log.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/1169387e9fa3d2a26b2e0fc46408b3cf3cd483861e70bc71143dbdd4acf0b470-image-20251203-143511.png",
        "",
        ""
      ],
      "align": "center"
    }
  ]
}
[/block]

6. For information on how to view your scan results, see [Viewing and Categorizing Scan Results](https://developer.onetrust.com/sdk/config/app-scanning/view-and-categorize-scan-results).

## Monitor Logs

1. In the OneTrust application, navigate to the **Logs** tab in the **Workflow Builder** screen.
2. Locate and select the **Event ID** to review the workflow log. You can also copy and paste the request ID to quickly locate the log.
3. Observe the new app name is present, with the correct platform type, and scan against the uploaded file.