Environments


Environments

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.

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.

Environments API operations

The environments endpoints support the following operations:

For hands-on experience with the environments API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Environments data model

Property Description
createdAt The time the resource was created.
description A string that specifies the description of the population.
id A string that specifies the resource’s unique identifier.
name A string that specifies the environment name, which must be provided and must be unique within an organization.
organization.id A string that specifies the organization resource’s unique identifier associated with the environment.
region A string that specifies the region in which this environment will be used. The value is set when the environment is created and cannot be updated. Options are NA, EU, and AU.
type A string that specifies the type of environment to use. Options are PRODUCTION and SANDBOX.
updatedAt The time the resource was last updated.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
403 You lack either the necessary permissions or the licensing to perform this operation.
404 The specified object doesn’t exist.

Endpoint examples

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.

Get one environment

The following sample shows the GET /environments/{environmentId} 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/{environmentId}" \
-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": "DevServ",
    "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"
}

Create environments

The following sample shows the POST /environments operation to create a new environment associated with the organization encoded in the access token.

curl -X POST "https://api.pingone.com/v1/environments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name": "String Factory Production Environment",
  "description": "North America Production Environment",
  "region": "EU",
  "type": "SANDBOX"
}"

In the request body, the name, region, and type attributes are required. The value of the name attribute must be unique within the organization.

Update environments

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

curl -X PUT "https://api.pingone.com/v1/environments/{environmentId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name": "Factory_Prod",
  "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.

Delete environments

The following sample shows the DELETE /environments/{environmentId} operation to delete the environment from the organization.

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

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