--- title: Environments description: 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. component: pingone-api page_id: pingone-api:platform:environments canonical_url: https://developer.pingidentity.com/pingone-api/platform/environments.html section_ids: environment-types: Environment types environments-and-product-types: Environments and product types roles-and-environments: Roles and environments assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service deleting-environments: Deleting environments restoring-environments: Restoring environments environments-data-model: Environments data model filtering-data: Filtering data environment-events-generated: Environment events generated response-codes: Response codes --- # 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. An environment also identifies the products and services that are enabled to address the deployment requirements. 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 products, such as PingFederate and PingAccess. An environment is the primary subdivision of an organization and contains the core resources on which all identity services are built. You can learn more about environments in [Environment Properties](https://docs.pingidentity.com/pingone/settings/p1_environments.html). ## Environment types There are two supported environment types: * `PRODUCTION` These environments contain the actual identities managed by your business. 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. `PRODUCTION` environments can't be immediately deleted, but must transition through a soft delete state with a waiting period before completing the delete operation (hard delete). Refer to [Deleting environments](#deleting-environments) below. * `SANDBOX` These environments are temporary configurations used primarily for configuration testing. Sandbox environments can be immediately deleted using the `DELETE {{apiPath}}/v1/environments/{{envID}}` request. A Sandbox environment cannot be restored. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can promote or demote environments to change their `type` property. Actors with the Environment Admin role have the required permissions to create new environments, and promote `SANDBOX` environments to `PRODUCTION`. | ### Environments and product types You'll find the product types (both PingOne and non-PingOne) that can be associated with a new environment in the `type` property of the Bill of Materials [Products data model](bill-of-materials-bom.html#products-data-model). ## Roles and environments 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. ```json "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. ```json "scope": { "id": "{{orgID}}", "type": "ORGANIZATION" }, "role": { "id": "{{environmentAdminRoleID}}" } ``` For additional information about role assignment scopes, refer to [Application role assignments](applications/application-role-assignments.html) and [User role assignments](users/user-role-assignments.html). ## Assigning admin roles and permissions to this service Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](group-role-assignments/group-role-assignments.html). * [User Role Assignments](users/user-role-assignments.html). Refer to [Roles Management](roles.html) for more information. ## Deleting environments You can delete a `PRODUCTION` environment if you have the Environment Admin role at the organization level, or the Organization Admin role. To delete an environment, use the [Update Environment Status](environments/update-environment-status.html) request, and set the status to `DELETE_PENDING`. This is called a soft delete. An environment that's been soft-deleted is not operational. `SANDBOX` environments are intended to be temporary, and are immediately deleted by calling the `DELETE {{apiPath}}/v1/environments/{{envID}}` request. These environments cannot be restored. A Production environment with a status of `DELETE_PENDING` is automatically set to a waiting period before complete deletion is possible. The waiting period duration is the time the environment was set to `DELETE_PENDING` (reflected in the `softDeletedAt` value) plus a period of 30 days. When the waiting period has elapsed, you can then call the [Delete Environment](environments/delete-environment.html) request to fully delete (hard delete) the environment. The time remaining for a hard delete to be possible is reflected in the `hardDeleteAllowed At` value. If at the time of the hard delete attempt the waiting period has not elapsed, the Delete Environment request will throw an error with the time the environment can be hard-deleted. | | | | - | --------------------------------------------------------------------------------------------------------------------- | | | All soft-deleted (`DELETE_PENDING`) environments that have exceeded the waiting period will be automatically deleted. | ### Restoring environments You can restore a `Production` environment having a `DELETE_PENDING` status if you have the Environment Admin role at the organization level, or the Organization Admin role. To restore an environment, use the [Update Environment Status](environments/update-environment-status.html) request, and set the status to `ACTIVE`. You'll also need to specify your PingOne license ID. ## 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, refer to [Bill of Materials](bill-of-materials-bom.html). | | `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. | | `hardDeleteAllowedAt` | Date | N/A | Read-only | The time when the soft-deleted Production environment (set to `DELETE_PENDING` status) can be completely deleted (a hard delete). When a soft-deleted environment is restored, this value is cleared. | | `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 geography 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`, `AU`, `SG`, or `AP`. | | `softDeletedAt` | Date | N/A | Read-only | The time the Production environment was set to the `DELETE_PENDING` status. When a soft-deleted environment is restored, this value is cleared. | | `status` | String | Optional\* | Mutable | The status of an environment. (\*Required for the [Update Environment Status](environments/update-environment-status.html) request.) This can be: null, `ACTIVE` and `DELETE_PENDING` (soft-delete). The maximum number of Production environments that can be in the `DELETE_PENDING` state is set to 100. | | `type` | String | Required | Mutable | The type of environment to use. Options are `PRODUCTION` and `SANDBOX`. | | `updatedAt` | Date | N/A | Read-only | The time the environment was last updated. | ## 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": ```none 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`, `status` * `and` (logical AND) Supported attributes: Used to connect multiple filters on any attribute. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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, refer to [Conventions](../foundations/conventions.html). ## Environment events generated Refer to [Audit Reporting Events](reference/audit-reporting-events.html) for the events generated. ### 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. |