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.
The following product types (both PingOne and non-PingOne) can be associated with a new environment:
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.These non-PingOne products can be included in the Bill of Materials:
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.
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.
For more information about SCIM syntax and operators, see Conventions.
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 |
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. |
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.