Organization REST APIs - v2
The Organization REST API allows you to create new organizations and browse the list of organizations.
Supported HTTP methods include:
- GET - Used to retrieve information, such as an individual organization or a list of organizations possibly filtered by names (this includes organization internal IDs and associated tags).
- GET - Previously used for retrieving roles and the mapping of those roles to an organization. Starting in version 70, this is deprecated and Authorization Configuration REST API - v2 should be used instead.
- POST - Used to create organizations.
- PUT - Previously used for authorization configuration for organizations (i.e. mapping users or groups to roles). Starting in version 70, this is deprecated and Authorization Configuration REST API - v2 should be used instead.
Supported operations include:
Add Organization
Creating an organization is quite simple, only requiring a unique name:
Item | Description |
---|---|
name | The name of the new organization. In the IQ Server GUI this corresponds to the "Organization Name" field. It must be unique. |
We'll be making a POST API call for this operation:
POST /api/v2/organizations
The JSON payload contains the name
parameter, for example:
{ "name": "My Organization" }
You can run the following cURL command to make the request:
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"name": "My Organization"}' 'http://localhost:8070/api/v2/organizations'
If your organization was successfully created, the system will respond with the following:
{ "id": "ab3d35233046480a9c30bb2437a48103", "name": "My Organization", "tags": [] }
Item | 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 are created at the organization level, and then applied to applications. A newly-created organization will have no tags. |
Note that the "id" returned is the ID of the new organization. This can be used in other operations that require an organization ID.
Get Organization
To get an individual organization by its internal ID we can issue the following GET request
GET /api/v2/organizations/{organizationId}
We can use cURL to make the request e.g.
curl -u admin:admin123 -X GET http://localhost:8070/api/v2/organizations/8e4f7ced6b9d462390f7df882b43c4fb
This will produce the information for the organization associated with the given internal ID in a JSON format e.g.
{ "id": "8e4f7ced6b9d462390f7df882b43c4fb", "name": "org", "tags": [{ "id": "ad748f7bb6f54dda9932b16c7c575a99", "name": "Mission Critical", "description": "Applications that are mission critical.", "color": "dark-red" }] }
Get Organizations
To get a list of organizations we must start with a GET call:
GET /api/v2/organizations?organizationName={YourOrganizationName}
NEW IN RELEASE 81 Note that the query parameter organizationName
is optional and if omitted will result in all of your viewable organizations.
We can use cURL to make the request (e.g. without the query parameter):
curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/organizations'
This will produce a list of all of your viewable organizations and associated information in a JSON format. Here is an example of what might be returned.
{ "organizations": [ { "id": "36d7e629462a4038b581488c347959bc", "name": "My Organization", "tags": [ ] }, { "id": "f48b5344fa204a4c88df96b2d455d521", "name": "My Organization 2", "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" } ] } ] }
Item | 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. |
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. |
Find the Currently Available Roles
Starting in version 70, this path is deprecated and Role REST API - v2 should be used.
Before mapping any roles, it’s a good idea to take a look at all the available roles for organizations. This can be done using a simple GET which is equivalent to that used for applications i.e.
GET /api/v2/applications/roles
This returns all the available roles for all organizations:
{ "roles": [ { "id": "2cb71b3468d649789163ea2e212b541e", "name": "Application Evaluator", "description": "Evaluates applications and views policy violation summary results." }, { "id": "90c7c98683b4471cb77a916744540bcc", "name": "Component Evaluator", "description": "Evaluates individual components and views policy violation results for a specified application." }, { "id": "1da70fae1fd54d6cb7999871ebdb9a36", "name": "Developer", "description": "Views all information for their assigned organization or application." }, { "id": "1cddabf7fdaa47d6833454af10e0a3ef", "name": "Owner", "description": "Manages assigned organizations, applications, policies, and policy violations." } ] }
Item | Description |
---|---|
id | This is the internal ID for the role. There is no corresponding field in the IQ Server GUI. |
name | This is the name of the role, which is exactly the same as the Role Name displayed in the IQ Server GUI. |
description | This provides a description of the level of access the role grants. |
As you may notice, there are four roles available for organizations at this time. Before proceeding to the next step, take note of the role
id
(in this example we will be adding an owner). This will be needed for mapping a user to the specific role.
Map Users to Roles
Starting in version 70, this path is deprecated and Authorization Configuration REST API - v2 should be used.
To map users to roles, we’ll need the id
(organization ID) from our successful organization creation, the role
id
for the role returned above that you will be mapping a user to, and the following information:
Item | Description |
---|---|
type | The type of user, which at this time, can only be either USER or GROUP. |
userOrGroupName | This is the username for the user you want to add to the role. If you are using LDAP and have configured it to work with the IQ Server, the LDAP user or group name can be used here. |
For this step, we’ll be using the following PUT API call…
PUT /api/v2/organizations/{organizationInternalId}/roleMembers
with an appended JSON-formatted body. Here is an example of the body that’s been formatted for easier review:
{ "memberMappings": [ { "roleId": "1cddabf7fdaa47d6833454af10e0a3ef", "members": [ { "type": "USER", "userOrGroupName": "user-owner" } ] } ] }
Putting this altogether, and using our cURL example, you should enter the following command:
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"memberMappings": [{"roleId": "1cddabf7fdaa47d6833454af10e0a3ef","members": [{"type": "USER","userOrGroupName": "user-owner"}]}]}' 'http://localhost:8070/api/v2/organizations/ab3d35233046480a9c30bb2437a48103/roleMembers'
As before, standard HTTP response codes will be returned.
You can map multiple roles in a single PUT.
Get All Role Members
Starting in version 70, this path is deprecated and Authorization Configuration REST API - v2 should be used.
To get the members of each role for an organization we can use this GET call:
GET /api/v2/organizations/{organizationInternalId}/roleMembers
We can use cURL to make the request:
curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/organizations/ab3d35233046480a9c30bb2437a48103/roleMembers'
This will produce the mappings from all roles to their members for your organization in a JSON format. Here is an example of what might be returned.
{ "memberMappings": [{ "roleId": "2cb71b3468d649789163ea2e212b541e", "members": [{ "type": "GROUP", "userOrGroupName": "(all-authenticated-users)" }] }, ... { "roleId": "1cddabf7fdaa47d6833454af10e0a3ef", "members": [{ "type": "USER", "userOrGroupName": "user-owner" }] }] }