Organizations REST API - v2
The Organizations REST API allows you to :
- Retrieve information on existing organizations (internal organization IDs, associated tags, etc.)
- Add new organizations
- Move organizations (Change the parent organization)
User Permissions Required to Invoke this API call
- Edit IQ Elements for all organizations referenced in the call
Methods supported
Examples of using GET
1. To get an individual organization by its organization ID:
GET /api/v2/organizations/{organizationId}Sample cURL:
curl -u admin:admin123 -X GET http://localhost:8070/api/v2/organizations/8e4f7ced6b9d462390f7df882b43c4fb
Response
This will produce the information for the organization associated with the given organization ID in a JSON format e.g.
{
"id": "8e4f7ced6b9d462390f7df882b43c4fb",
"name": "org",
"parentOrganizationId": "9b0a94c9187e46cca05866208a7d79cb"
"tags": [{
"id": "ad748f7bb6f54dda9932b16c7c575a99",
"name": "Mission Critical",
"description": "Applications that are mission critical.",
"color": "dark-red"
}]
}View Explanation of Response Fields for GET Request
2. To get a list of all organizations:
GET /api/v2/organizations?organizationName={YourOrganizationName}Note that the query parameter organizationName is optional and if omitted will result in all of your viewable organizations.
Sample cURL (without the query parameter):
curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/organizations'
Response
This will generate a list of all of your viewable organizations and associated information in a JSON format.
{
"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"
}
]
}
]
}View Explanation of Response Fields for GET Request
Examples of using POST
1. To create a new organization "My Organization." The name of the organization provided should be unique.
POST /api/v2/organizations
Payload example:
{
"name": "My Organization"
}Sample cURL:
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"name": "My Organization"}' 'http://localhost:8070/api/v2/organizations'Response
A new organization will be created under the root level. The response will show the organization ID and tags created for the organization name in a JSON format
{
"id": "ab3d35233046480a9c30bb2437a48103",
"name": "My Organization",
"parentOrganizationId": "ROOT_ORGANIZATION_ID"
"tags": []
}NEW IN RELEASE 156 2. To create a new organization as a sub-Org, linked to an existing organization.
This functionality supports the n-level hierarchy model.
POST /api/v2/organizations
Payload example:
{
"name": "test-grand4-child",
"parentOrganizationId": "9b0a94c9187e46cca05866208a7d79cb"
}Response
{
"id": "9a2949f1421b4030aafa6f8e038aaf63",
"name": "test-grand4-child",
"parentOrganizationId": "9b0a94c9187e46cca05866208a7d79cb",
"tags": []
}Explanation of Response Fields for 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 for 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, which 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. |
NEW IN RELEASE 161 Examples of using PUT
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 N-Level hierarchy model.
PUT /api/v2/organizations/{organizationId}/move/destination/{destinationId}where organizationId refers to the organization that is being moved and destinationId is the organization ID of the new parent in the hierarchy.
Response
An HTTP response code 200 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.
An HTTP response code 409 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"
}
]
}Explanation of Response Fields for POST request
Response Field | Description |
|---|---|
| errors | This field will contain a list of errors that are preventing moving the organization under a new parent in the hierarchy. Expected values for error types are TAG, POLICY, LICENSE_THREAT_GROUP, LABEL, or 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, or POLICY_WAIVER |
Other Related APIs:
- To retrieve all the available roles for organizations, use Role REST API - v2
- To retrieve all users belonging to a role group or map users to a role group , use Authorization Configuration REST API - v2