Skip to main content

Organizations REST API

The Organizations REST API is for querying, adding, and editing organizations in IQ Server. The 'Edit IQ Elements' permissions are needed for the organizations referenced in the call.

Get a list of organizations

Fetch all organizations or query for a specific one. The response will include the organization's parent org as well as any application tags configured at this level.

Get all organizations

GET /api/v2/organizations

To get a specific organization by its organization ID

GET /api/v2/organizations/{organizationId}

Query for a specific organization by name.

GET /api/v2/organizations?organizationName={YourOrganizationName}

Example using the organization ID:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/organizations/8e4f7ced6b9d462390f7df882b43c4fb

Example Response:

{
    "organizations": [
        {
            "id": "36d7e629462a4038b581488c347959bc",
            "name": "My Organization",
                        "parentOrganizationId": "9b0a94c9187e46cca05866208a7d79cb"
            "tags": [ ]
        },
        {
            "id": "f48b5344fa204a4c88df96b2d455d521",
            "name": "My Organization 2",
                        "parentOrganizationId": "9b0a44c9187e46cca05866208a7d79cb"
            "tags": [
                {
                    "id": "cd8fd2f4f289445b8975092e7d3045ba",
                    "name": "Distributed",
                                        "description": "Applications that are provided for consumption outside the company",
                    "color": "yellow"
                },
                {
                    "id": "004d789684834f7c889c8b186a5ff24b",
                    "name": "Hosted",
                                        "description": "Applications that are hosted such as services or software as a service.",
                    "color": "grey"
                },
                {
                    "id": "da9e09887c754157a2113831ae7e99ac",
                    "name": "Internal",
                    "description": "Applications that are used only by your employees",
                    "color": "green"
                }
            ]
        }
    ]
}

Adding organizations using POST request

To add a new organization named "My Organization." The name of the organization provided should be unique. When leaving out a parent organization the new organization will be added to the root organization.

POST /api/v2/organizations

Payload example:

{
    "name": "My Organization"
}

Payload example with a parent organization. You must include the organization ID of the parent.

{
    "name": "test-grand4-child",
    "parentOrganizationId": "9b0a94c9187e46cca05866208a7d79cb"
}

Sample cURL:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"name": "My Organization"}' 'http://localhost:8070/api/v2/organizations'

Example POST response

{
    "id": "ab3d35233046480a9c30bb2437a48103",
    "name": "My Organization",
        "parentOrganizationId": "ROOT_ORGANIZATION_ID"
    "tags": []
}

Moving an organization using PUT request

Use the PUT method to change the parent organization to a new parent organization in the hierarchy. This can be used to transition an existing single organization-level hierarchy to Hierarchy And Inheritance.

PUT /api/v2/organizations/{organizationId}/move/destination/{destinationId}

The organization ID refers to the organization that is being moved and the destination ID is the organization ID of the new parent.

200 - HTTP response code indicates that the organization has been successfully moved under a new parent in the hierarchy. The JSON response may list warnings if any, even if the move is successful.

409 - HTTP response code indicates that the organization could not be moved due to conflicts/causes listed in the "errors" response field.

{
  "errors": [
    {
      "message": "New parent org Org Level 2 is already set and in use as the parent of org Org 2 Level 3",
      "type": "PARENT_HIERARCHY"
    }
  ],
  "warnings": [
    {
      "message": "Some policy waivers that were previously inherited no longer apply in the new parent organization.",
      "type": "POLICY_WAIVER"
    }
  ]
}

Response fields for successful GET and POST requests

Response Field

Description

id

This is the internal ID for the organization.

name

This is the name of the organization and is visible in the IQ Server GUI.

tags

Tags represent identifying characteristics of an application. Tags are created at the organization level and then applied to applications. Policies can then select which tags, and in turn applications, the policy will be evaluated against.

parentOrganizationId

Internal ID of the parent organization to which the new organization is linked.

id (tags)

The internal ID for the tag. This will be used when creating the application.

name (tags)

The name of the tag, is visible in the IQ Server GUI.

description (tags)

Each tag is required to have a description. This description provides information related to the type of application it should be applied to.

Error response fields for POST request

Response Field

Description

errors

This field will contain a list of errors that prevent moving the organization under a new parent in the hierarchy.

Expected values for error types are:

TAG, POLICY, LICENSE_THREAT_GROUP, LABEL, PARENT_HIERARCHY

warnings

This shows any license, waivers, or policy monitoring messages associated with the organization that may no longer be applicable to the new parent organization.

Expected values for warnings are:

LICENSE_OVERRIDE, POLICY_MONITORING, POLICY_WAIVER