Application REST API

The Application REST API is for managing applications in the IQ Server.

Getting the Application ID

The application ID is the internal system reference created when adding an application to the IQ Server. Use this identifier to reference the application in most REST API calls reference a specific application. Find the application ID from the Application REST API using the Public ID assigned by your organization to the application when it was created. The Public ID is located under the application name in the IQ Server user interface.

GET /api/v2/applications?publicId={PublicId}

The application ID is labeled as 'id' in the response metadata for the application.

{ "applications": [
  {
    "id": "4537e6fe68c24dd5ac83efd97d4fc2f4",
    "publicId": "MyApplicationID",
    "name": "MyApplication",
    "organizationId": "bb41817bd3e2403a8a52fe8bcd8fe25a",
    "contactUserName": "NewAppContact",
    "applicationTags": [
      {
        "id": "9beee80c6fc148dfa51e8b0359ee4d4e",
        "tagId": "cfea8fa79df64283bd64e5b6b624ba48",
        "applicationId": "4bb67dcfc86344e3a483832f8c496419"
      }
    ] 
  }
]}

Getting All Applications

Retrieve all applications

GET /api/v2/applications

curl -u [token]:{password} http://localhost:8070/api/v2/applications

The endpoint returns all of the applications the user has read permissions to access.

Here is an example of what might be returned.

{ "applications": [
 {
   "id": "e1db2d3f4ccf40a38f193183bffdb7e5",
   "publicId": "app1",
   "name": "app1",
   "organizationId": "8162c39152974035b8d66df12f5abe7d",
   "contactUserName": null,
   "applicationTags": []
 },
 {
   "id": "47951e63ddd742868484dee8630767bc",
   "publicId": "app3",
   "name": "app3",
   "organizationId": "3e9d988f6727420ea445b02fbeaf73e9",
   "contactUserName": null,
   "applicationTags": [
     {
       "id": "feaf2c2e33854216bd47f62d9d5371a8",
       "tagId": "131765d40bee47fb9be5bc60d7b52cce",
       "applicationId": "47951e63ddd742868484dee8630767bc"
     }
   ]
  }
]}

Filter applications using the public ID

Filter results by specifying application public IDs as optional query parameters. More than one application's public ID may be queried in a single call.

curl -u admin:admin123 http://localhost:8070/api/v2/applications?publicId=app1&publicId=app2

Filter applications by organization

Retrieve the applications for a given organization

GET /api/v2/applications/organization/{organizationId}

curl -u admin:admin123 http://localhost:8070/api/v2/applications/organization/8162c39152974035b8d66df12f5abe7d

This example returns all of the applications for the organization with the id matching the organizationId.

Including application categories in results

The details of the applied application tags (also called application categories) can be directly included in the response using the optional query parameter

includeCategories

curl -u admin:admin123 http://localhost:8070/api/v2/applications?includeCategories=true

{ "applications": [
  {
    "id": "47951e63ddd742868484dee8630767bc",
    "publicId": "app3",
    "name": "app3",
    "organizationId": "3e9d988f6727420ea445b02fbeaf73e9",
    "contactUserName": null,
    "categories": [
      {
        "id": "131765d40bee47fb9be5bc60d7b52cce",
        "name": "Distributed",
        "description": "Applications that are provided for consumption outside the company",
        "organizationId": "ROOT_ORGANIZATION_ID",
        "color": "yellow"
      }
    ]
  }
]}

Adding Applications using the REST API

When adding a new application to IQ Server we recommend including the application context (the application categories and organization the application will belong to) and access control (who owns and has access to the application). Consider using automatic applications when setting the organization and access controls are not required.

Step 1 - Get the Organization ID

To create a new application, it must have the parent organization from which it will be a member of. All applications must belong to an organization.

Use the Organization REST API to retrieve the organization ID.

Step 2 - Create an Application

You need the application details listed below when adding an application:

Item	Description
publicId	This required field is the user-created identifier is assigned to the application for use with integrations and during the build analysis. The public ID must be unique.
name (application name)	This required field is the 'friendly' user-created name of the application used in reports and through the user interface. The application name must be unique.
organization ID	This required field is the parent organization for the application. Applications belong to a single organization. Organizations should be added before adding their applications. Use the Organization REST API to retrieve the organization ID.
contactUserName (application contact)	In the IQ server user interface, this corresponds to the contact field for the application. The optional value is the username for the application owner.
applicationTags	The optional 'applicationTags' are the internal identifier of the Application Category to apply to the application. Application Categories allow policy to be scoped to a specific application context. Use the Application Categories from the parent organization Use the Application Categories API to manage the available categories

Adding an application uses the POST request on the /applications endpoint.

POST /api/v2/applications

The application details are included in a JSON-formatted body of the POST request. Follows is an example of the body that’s been formatted:

{
  "publicId": "MyApplicationID",
  "name": "MyFirstApplication",
  "organizationId": "f48b5344fa204a4c88df96b2d455d521",
  "contactUserName": "AppContact",
  "applicationTags": [
    {
      "tagId": "cd8fd2f4f289445b8975092e7d3045ba"
    }
  ]
}

Put together you will have something like the following command:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"publicId": "MyApplicationID","name": "MyFirstApplication","organizationId":"f48b5344fa204a4c88df96b2d455d521","contactUserName":"AppContact","applicationTags": [{"tagId":"cd8fd2f4f289445b8975092e7d3045ba"}]}' 'http://localhost:8070/api/v2/applications'

When the request is successful, the system responds with the newly added application object:

{
    "id": "4bb67dcfc86344e3a483832f8c496419",
    "publicId": "MyApplicationID",
    "name": "MyFirstApplication",
    "organizationId": "f48b5344fa204a4c88df96b2d455d521",
    "contactUserName": "AppContact",
    "applicationTags": [
        {
            "id": "9beee80c6fc148dfa51e8b0359ee4d4e",
            "tagId": "cd8fd2f4f289445b8975092e7d3045ba",
            "applicationId": "4bb67dcfc86344e3a483832f8c496419"
        }
    ]
}

Step 3 - Set the application access controls

When setting application access controls, the best practice is to configure access to a group of users at the highest organizational level and allow inheritance to assign access to the applications managed by that organizational group. However, access may be configured at the application level as well.

Access is granted by assigning specific users or groups to the application as a specific role.

Look up the available roles using the Role REST API
Look up the groups or users to add using the User REST API
Note: SAML users need to have logged into the IQ server at least once to be discoverable by the IQ server's API as IQ server cannot query all users from the IdP.
Use the Authorization Configuration REST API to assign groups/users to a specific role for the organization or application.
For example: Assign the development team (group) the Developer role to the application's parent organization.

Update Application Information

The following application metadata may be modified after adding the application.

"publicId" - When changing the public ID, remember to update your integration and build tools to use the new value.
"name" - The name will need to be unique or the request will fail.
"contactUserName" - The username of the owner responsible for the application used in the UI and reports.
"applicationTags" (tagID) - Application categories assigned to the application used to scope policy.

The following identifiers may not be modified:

"id" - This is the internally assigned application ID used to reference the application.
"organizationId" - The parent organizational group to which the application belongs. See the "Moving an Application to a Different Organization" section to change the application's organization.

Use the same request body object from adding a new application when making the PUT update request.

Example Request

curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"id":"4bb67dcfc86344e3a483832f8c496419","publicId":"MyApplicationID","name":"MySecondApplication","organizationId":"bb41817bd3e2403a8a52fe8bcd8fe25a","contactUserName":"NewAppContact","applicationTags":[{"tagId":"cfea8fa79df64283bd64e5b6b624ba48"}]}' 'http://localhost:8070/api/v2/applications/4bb67dcfc86344e3a483832f8c496419'

When successful the request will return the updated application object.

Moving an Application to a Different Organization

An application may be moved from one organization to another using the request:

POST /api/v2/applications/{applicationInternalId}/move/organization/{organizationId}

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/applications/4bb67dcfc86344e3a483832f8c496419/move/organization/bb41817bd3e2403a8a52fe8bcd8fe25a

The possible responses are as follows:

If the application is successfully moved to the target organization, status code 200 will be returned with an empty body.
Moving an application to a different organization can be successful albeit with warnings. In this case, status code 200 is returned with a body containing the warnings as follows:

{
  "warnings": [
    "Some policy waivers (1 in total) that were previously inherited no longer apply in the new parent organization.",
    "Some component labels (2 in total) that were previously inherited no longer exist in the new parent organization.",
    "Some license overrides (3 in total) that were previously inherited no longer exist in the new parent organization."
  ]
}

Moving an application to an organization can fail due to conflicts between the organizations the application is moved between. In this case status code 409 is returned with errors as follows:

{
  "errors": [
    "The application category 'Internal' from the organization 'Source-Organization' has no counterpart in the new parent organization.",
    "The policy 'Internal-Policy' from the organization 'Source-Organization' has no counterpart in the new parent organization."
  ]
}

If either an application with the provided "applicationInternalId" or an organization with the submitted "organizationId" is not found, this request yields status code 404.
Trying to move an application to the same organization yields status code 400.

Deleting an Application

Permanently delete an application

Warning

Deleting an application will permanently remove the application and all scan data associated with it.

DELETE /api/v2/applications/{applicationInternalId}

curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/applications/4bb67dcfc86344e3a483832f8c496419'

Standard HTTP status codes are returned in response to the request.