Work with environments and populations


Environments and populations

Every organization contains at least one environment resource. In large global enterprises, there can be several environments. These environments are often based on region, or they serve as the defining entity to segregate enterprise operations by functionality, staging environments, or configurations.

Environment resources contain population resources, which provide the structure to manage groups of similar users within the environment. The following diagram shows this relationship.

Environments and Populations

Note: You need the Environment Admin role to perform operations on environment and the Identity data Admin role to perform operations on population resources. For more information, see Work with user roles.

Filtering result data

GET requests that return environment resources support the sw (starts with) SCIM filtering expression. This filter can be appended to the request URL to fine-tune the result data. For example, this filter returns only the environments in which the name attribute value starts with the letter “S”:

https://api.pingone.com/v1/environments?filter=name%20sw%20%22S%22

These SCIM operators can be applied to the following attributes:

  • sw (starts with)

    Supported attributes: name

Note: These SCIM operators are not supported: eq (equal to), gt (greater than), lt (less than), ge (greater than or equal to), le (less than or equal to), in (includes), ne (not equal), co (contains), ew (ends with), pr (present, is a non-empty or non-null value), not (logical NOT), or (logical OR), and (logical AND). Populations do not support SCIM filtering expressions.

For more information about SCIM syntax and operators, see Conventions.

Get environments

You can get all environment resources for an organization, a selected set of environments (using a filter), or a specific environment.

The following sample shows the GET /environments operation to return all environments associated with the organization:

curl -X GET "https://api.pingone.com/v1/environments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

Note: The organization ID does not need to be specified because it is encoded in the access token.

The following sample shows the GET /environments/{id} operation to return data only for the environment resource identified by its ID in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/01db3f1e-7ae3-49ac-af9b-9498b0a31bdf" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data shows the environment resource data and all related resources links.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/ddb8e223-10a0-4b96-9298-d306ae84ef46"
        },
        "populations": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations"
        },
        "users": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/users"
        },
        "applications": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications"
        },
        "clients": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/clients"
        },
        "activities": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/activities"
        },
        "branding": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/branding"
        },
        "features": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/features"
        },
        "resources": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/resources"
        },
        "scopes": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/scopes"
        },
        "importTasks": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/importTasks"
        },
        "passwordPolicies": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies"
        },
        "userActivities": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/userActivities"
        },
        "signOnPolicies": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies"
        }
    },
    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba",
    "name": "Caladan",
    "organization": {
        "id": "ddb8e223-10a0-4b96-9298-d306ae84ef46"
    },
    "type": "SANDBOX",
    "region": "NA",
    "createdAt": "2018-05-23T15:59:04.654Z",
    "updatedAt": "2018-05-23T15:59:04.654Z"
}

Update environments

To update the configuration of your environment, you can use PUT /environments/{id} to modify the property attributes of the specified environment. The following is a sample in which a SANDBOX environment resource type attribute is changed to PRODUCTION:

curl -X PUT "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name": "String Factory Production Environment",
  "description": "North America Production Environment",
  "type": "PRODUCTION"
}"

In the request body, the type attribute is updated to PRODUCTION and the name and description attributes are modified to describe this resource as the production environment.

Note: The environment’s region attribute cannot be modified in a PUT request. The region attribute value is defined when the environment resource is created (POST request) and cannot be changed.

Get populations

The populations API implements functions to create, read, update, delete, and search for population resources within a specified environment.

The following sample shows the GET /environments/{environmentId}/populations operation to return the complete list of population resources associated with the specified environment.

curl -X "GET" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/populations" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The request returns a list of populations resources. The returned data includes the id, which is the population ID required for many user-related API calls. It also shows the userCount attribute, which identifies the number of users associated with the population.

The response data for an environment with two populations resources looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations"
        }
    },
    "_embedded": {
        "populations": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/5e5cf2d4-2e11-4efc-89f1-73110c277ded"
                    }
                },
                "id": "5e5cf2d4-2e11-4efc-89f1-73110c277ded",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Accounting",
                "userCount": 6,
                "createdAt": "2018-06-12T19:09:23.756Z"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/14865d2f-5c28-40a2-97e7-10cb921e2ade"
                    }
                },
                "id": "14865d2f-5c28-40a2-97e7-10cb921e2ade",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Engineering",
                "userCount": 31,
                "createdAt": "2018-06-12T19:09:42.504Z"
            }
        ]
    },
    "count": 2,
    "size": 2
}

Update populations

To update a population resource, you need to know the environment ID and the ID of the population to modify.

You can use PUT /environments/{environmentId}/populations/{populationId} to update the attribute values for a population in the specified environment.

curl -X PUT "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede/populations/21731b50-6b54-41b0-8454-9cd9de62a7a1" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name" : "Finance and Accounting",
  "description" : "Finance and accounting group",
}"

In the request body, the population name is changed to Finance and Accounting, and the value of the description attribute is modified to indicate that the population includes finance and accounting users.

Delete populations

You can perform a DELETE operation on the population resource to remove it from the environment. the population must not have any associated users before it can be deleted. You can verify that the population resource is empty by calling GET /environments/{environmentId}/populations/{populationId} to view the userCount value.

The following sample shows the DELETE /environments/{environmentId}/populations/{populationId} operation to delete the empty population from the specified environment.

curl -X DELETE "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede/populations/21731b50-6b54-41b0-8454-9cd9de62a7a1" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \

When successful, the DELETE request returns a code 204 No Content message.