PingOne Platform APIs

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.

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 cannot 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 below.

  • SANDBOX

    These environments are temporary configurations used primarily for configuration testing. Sandbox environments can be immediately deleted using the DELETE {{apiPath}}/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.

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.

"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, refer to Application role assignments and User role assignments.

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 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}}/environments/{{envID}} request. These environments cannot be restored.

An 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 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 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.

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.

hardDeletedAllowedAt

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 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, 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 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":

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.

Environment events generated

Refer to Audit Reporting Events 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.