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 data

GET requests that return environment resources support SCIM filtering expressions. The query filter can be appended to the request URL to fine-tune the response data. For example, the following 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

  • eq (equal to)

    Supported attributes: id, organization.id

  • and (logical AND)

    Supported attributes: Used to connect multiple filters on any attribute.

Note: These SCIM operators are not supported: 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). 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 could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.

Endpoint examples

You need the Environment Admin role to perform operations on environment resources. To create environments, you must have either an Organization Admin role or an Environment Admin role at the organization level. An Environment Admin role at the environment level (applicable to a specific environment) cannot create new environments.

The role assignment scope determines the domain of the role. For example, the following role assignment resource shows that this Environment Admin role has a scope that applies only to an environment. An actor with this Environment Admin role cannot create a new environment.

"scope": {
    "id": "{environmentId}",
    "type": "ENVIRONMENT"
},
"role": {
    "id": "{EnvironmentAdminRoleId}"
}

Conversely, an actor with an Environment Admin role assignment scope that specifies the organization resource can create new environments. For example, the scope id for the following role assignment designates an organization resource ID as the scope domain. An Environment Admin with this role assignment scope has permission to create new environments.

"scope": {
    "id": "{organizationId}",
    "type": "ORGANIZATION"
},
"role": {
    "id": "{EnvironmentAdminRoleId}"
}

For additional information about role assignment scopes, see Application role assignments and User role assignments.

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 /organizations/{organizationId}/environments operation to return all environments associated with the organization:

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

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 "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/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/4235cade-f281-4a5c-80e1-07b0c1cb3cdb"
        },
        "populations": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/populations"
        },
        "users": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users"
        },
        "applications": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications"
        },
        "activities": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/activities"
        },
        "branding": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/branding"
        },
        "features": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/features"
        },
        "resources": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/resources"
        },
        "scopes": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/scopes"
        },
        "importTasks": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/importTasks"
        },
        "passwordPolicies": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/passwordPolicies"
        },
        "userActivities": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/userActivities"
        },
        "signOnPolicies": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/signOnPolicies"
        },
        "keys": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/keys"
        },
        "templates": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/templates"
        },
        "notificationsSettings": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/notificationsSettings"
        },
        "schemas": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/schemas"
        }
    },
    "id": "88c23def-39c9-4646-8d41-aa91a14a1006",
    "name": "Test Env One",
    "description": "For simulated traffic.",
    "organization": {
        "id": "4235cade-f281-4a5c-80e1-07b0c1cb3cdb"
    },
    "type": "SANDBOX",
    "region": "NA",
    "createdAt": "2018-08-22T01:57:50.079Z",
    "updatedAt": "2018-08-31T17:56:45.074Z"
}

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 Environment",
  "region": "NA",
  "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.

Note: If a worker application creates a new environment, that worker application is given an Identity Data Admin role assignment for that environment automatically. Only the worker application can perform Identity Data Admin operations in that environment. However, the worker application can give the same role assignment to another user or another worker application. For more information about roles, see Roles.

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.

Update environment type

To update the environment type, you can use PUT /environments/{environmentId}/type to modify the type attribute value 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}/type" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "type": "PRODUCTION"
}"

Delete environments

You can delete an environment resource, but only if the type attribute is set to SANDBOX. Production environments cannot be deleted. The following sample shows the DELETE /environments/{environmentId} operation to delete an environment from the organization.

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

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