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 the list of organizations (including their 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:

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": []
}

Get All Organizations

To get a list of the organizations we must start with a GET call:

GET /api/v2/organizations

We can use cURL to make the request:

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

This will produce a list of your 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"
                }
            ]
        }
    ]
}

Find the Currently Available Roles

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."
        }
    ]
}

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

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:

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.

Get All Role Members

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"
		}]
	}]
}