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 Protect. 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:

PING_ONE_MFA
PING_ONE_RISK
PING_ONE_VERIFY
PING_ONE_CREDENTIALS
PING_ONE_AUTHORIZE
PING_ONE_PROVISIONING
PING_ONE_BASE Specifies the PingOne platform API, which includes all PingOne capabilities.

Non-PingOne products

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

PING_FEDERATE
PING_ACCESS
PING_DIRECTORY
PING_DATA_SYNC
PING_DATA_GOVERNANCE
PING_ONE_FOR_ENTERPRISE
PING_ID
PING_ID_SDK
PING_CENTRAL
PING_INTELLIGENCE
PING_ONE_FOR_SAAS
PING_AUTHORIZE

Environment types

There are two supported environment types:

PRODUCTION

These environments contain the actual identities managed by your business. Production environments cannot be deleted (unless they are first demoted to a SANDBOX type), which offers additional protection against unintentional removal. You must have a non-Trial license to create or promote an environment to the PRODUCTION type. Any long-standing environments, even those used for testing and staging, should be configured as PRODUCTION to minimize the risk of data loss.
SANDBOX

These environments are temporary configurations used primarily for configuration testing. Sandbox environments can be deleted using the DELETE /environments/{{envID}} endpoint operation.

Note: You can promote or demote environments to change their type property. Actors with the PingOne Environment Admin role have the required permissions to create new environments, promote SANDBOX environments to PRODUCTION, and demote PRODUCTION environments to SANDBOX.

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, license.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).

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

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Service	Event
`environments`	`ENVIRONMENT.CREATED`
`environments`	`ENVIRONMENT.UPDATED`
`environments`	`ENVIRONMENT.PROMOTED`
`environments`	`ENVIRONMENT.DELETED`

Environments data model {#environments-data-model}

Property	Type	Required?	Mutable?	Description
`billOfMaterials`	Object	Optional	Mutable	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]`	Array	Optional	Mutable	Products that specify the PingOne and non-PingOne products and services that are associated with this environment deployment.
`billOfMaterials.products[0].id`	String	Required	Immutable	The Product’s ID.
`billOfMaterials.products[0].type`	String	Optional	Mutable	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`	String	Optional	Mutable	The product’s description.
`billOfMaterials.products[0].console`	String	Optional	Mutable	The URL to the product’s admin console.
`billOfMaterials.products[0].softwareLicense.id`	String	Optional	Immutable	The software license ID associated with this product.
`billOfMaterials.products[0].deployment.id`	String	Optional	Immutable	The external resource ID associated with this product, containing state and settings information related to the external resource associated with this product.
`createdAt`	Date	N/A	Read only	The time the resource was created.
`description`	String	Optional	Mutable	The description of the population.
`icon`	String	Optional	Mutable	The URL referencing the image to use for the environment icon. The supported image types are JPEG/JPG, PNG, and GIF.
`id`	String	Required	Immutable	The resource’s unique identifier.
`license.id`	String	Required	Immutable	The active license associated with this environment. This property is required only if your organization has more than one active license.
`name`	String	Required	Mutable	The environment name, which must be provided and must be unique within an organization.
`organization.id`	String	Optional	Immutable	The organization resource’s unique identifier associated with the environment.
`region`	String	Required	Immutable	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”, “CA”, “EU”, or “AP”.
`type`	String	Required	Mutable	The type of environment to use. Options are `PRODUCTION` and `SANDBOX`.
`updatedAt`	Date	N/A	Read only	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": "{{envID}}",
    "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": "{{orgID}}",
    "type": "ORGANIZATION"
},
"role": {
    "id": "{{environmentAdminRoleID}}"
}

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