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.

An environment also identifies the products and services that are enabled to address the requirements of the deployment. For example, an environment can identify enabled PingOne services that are hosted on the PingOne platform, such as PingOne MFA and PingOne Risk. The environment can also identify supported non-PingOne product such as PingFederate and PingAccess.

Environments and product types

The following product types (both PingOne and non-PingOne) can be associated with a new environment:

PingOne products

These PingOne products can be included in the Bill of Materials:

Non-PingOne products

These non-PingOne products can be included in the Bill of Materials:

Environment types

There are two supported environment types:

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:

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

Environments data model

Property Description
billOfMaterials An object that specifies the Bill of Materials for the environment. This is an optional property. Create requests that do not specify this property receive a default PingOne Bill of Materials on creation. For more information, see Bill of Materials.
billOfMaterials.products[0] An array of products that specify the PingOne and non-PingOne products and services that are associated with this environment deployment.
billOfMaterials.products[0].id A string that specifies the Product’s ID.
billOfMaterials.products[0].type A string that specifies the Product type. Options for PingOne products are PING_ONE_MFA, PING_ONE_RISK, PING_ONE_PROVISIONING, and PING_ONE_BASE. Options for non-PingOne product are PING_FEDERATE, PING_ACCESS, PING_DIRECTORY, PING_DATA_SYNC, PING_DATA_GOVERNANCE, PING_ONE_FOR_ENTERPRISE, PING_ID, PING_ID_SDK, PING_CENTRAL, and PING_INTELLIGENCE.
billOfMaterials.products[0].description A string that specifies the product’s description.
billOfMaterials.products[0].console A string that specifies the URL to the product’s admin console.
billOfMaterials.products[0].softwareLicense.id A string that specifies the software license ID associated with this product.
billOfMaterials.products[0].deployment.id A string that specifies the external resource ID associated with this product, containing state and settings information related to the external resource associated with this product.
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.
license.id A string that specifies the active license associated with this environment. This property is required only if your organization has more than one active license.
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 AP.
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.

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.