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

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.

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 for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management 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 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 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

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

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.

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 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
co (contains)

Supported attributes: name
eq (equal to)

Supported attributes: id, envId, orgId, organization.id, pingoneAccountId, 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), 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.

Environment errors

In addition to the general error codes, environment operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`INVALID_DATA`	`EMPTY_VALUE`	Message: `Validation Error : [<property> must not be null]` When and details When: A `POST` or `PUT /environments` request omits one of the required properties: `name`, `type`, or `region` Details: Target is the omitted property.
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST` or `PUT /environments` request supplies a `name` that does not match the object name rules, or a `description` that does not match the description character rules Details: `must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens` for `name`, or must contain only Unicode letters, marks, numbers, spaces, or punctuation (except $, +, <, =, >, ^, `, \|, ~) for `description`, for example: Validation Error : [name must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens]
400	`INVALID_DATA`	`OUT_OF_RANGE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST` or `PUT /environments` request supplies a `name` longer than 256 characters, or a `description` longer than 1024 characters Details: `size must be between 1 and 256` for `name`, or `size must be between 1 and 1024` for `description`, with `rangeMinimumValue` and `rangeMaximumValue` inner errors, for example `Validation Error : [name size must be between 1 and 256]`.
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST` or `PUT /environments` request, a `PUT /environments/{ID}/type` request, or a `PUT /environments/{ID}/status` request supplies a `type` or `status` value that is not one of the allowed values Details: `must be one of the values: SANDBOX, PREPRODUCTION, or PRODUCTION` for `type`, or `must be one of the values: ACTIVE or DELETE_PENDING` for `status`, for example `Validation Error : [type must be one of the values: SANDBOX, PREPRODUCTION, or PRODUCTION]`. Setting `type` to `PREPRODUCTION` when the `P14C-72721_allow_preproduction_environment_type` feature flag is off for the organization returns the same top‑level code and message, with the detail `The PREPRODUCTION environment type requires enabling the Feature Flag: P14C-72721_allow_preproduction_environment_type` (target `type`)
400	`INVALID_DATA`	`UNIQUENESS_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /environments` request creates an environment with a name that already exists in the organization, or a `PUT /environments/{ID}` request renames the environment to one that does Details: `Environment already exists with the name '<name>'`
400	`INVALID_DATA`	`REQUIRED_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /environments` request from an actor whose access token does not identify an organization omits `organization.id` from the request body Details: `For actors without an associated organization, organization must be specified in the request body.`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /environments` request specifies a `region` that is not supported by the endpoint that received the request Details: `Environment cannot be created in specified region by this service endpoint.`, with an `allowedValues` inner error listing the regions supported by the endpoint.
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST` or `PUT /environments` request, or a `PUT /environments/{ID}/status` request setting `status` to `ACTIVE`, specifies a `license.id` that fails one of the license assignment validations Details: One of `License specified to be assigned to this environment does not exist.`, `License specified to be assigned to this environment does not support environment region.`, `License specified to be assigned to this environment does not support production environments.`, `does not support assigning a Pingone account id`, `License specified to be assigned to this environment cannot be assigned to additional environments.`, `The License specified has a start date in the future and cannot be used yet.`, or `Cannot provision license of package <licensePackage>.`
400	`INVALID_DATA`	`REQUIRED_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /environments` request specifies neither `license.id` nor `license.package`, and the organization has no licenses that can be assigned to additional environments, or has more than one, so the request must specify a license Details: `No active licenses exist for organization that can be assigned to additional environments.` or `Multiple licenses are active for organization, so license must be specified in request.`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `PUT /environments/{ID}` request assigns a different license to an environment that has `DELETE_PENDING` status Details: `A license cannot be assigned to an environment with status DELETE_PENDING`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `PUT /environments/{ID}/status` request sets `status` to `ACTIVE` without specifying a `license.id` Details: `licenseId is required when setting the status to ACTIVE.`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `PUT /environments/{ID}/status` request targets an environment whose type is not `PRODUCTION` (allowed only when the soft delete demotion override feature flag is enabled for the organization) Details: `Cannot update status on environments other than PRODUCTION.`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `PUT /environments/{ID}/status` request sets `status` to `DELETE_PENDING` when the organization has reached its maximum number of soft deleted environments (100) Details: `Environment cannot be soft deleted as the maximum number of soft deleted environments has been reached.`
400	`INVALID_DATA`	None	Message: `Soft Deleted Environment cannot be hard deleted until <hardDeleteAllowedAt>` When and details When: A `DELETE /environments/{ID}` request hard deletes a `PRODUCTION` environment whose `DELETE_PENDING` waiting period has not elapsed Details: None.
400	`INVALID_REQUEST`	None	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A request body is missing or cannot be parsed as JSON, or an environment ID in the request path cannot be parsed as a UUID Details: None. For an unparseable path UUID the top-level code stays `INVALID_REQUEST` but the message reads `The request could not be completed. One or more validation errors were in the request.`
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `DELETE /environments/{ID}` request, or a `PUT /environments/{ID}/status` request setting `DELETE_PENDING`, targets the environment that the actor belongs to Details: `Cannot delete an Environment (ID: '<id>') that you as a user belong to.`
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `PUT /environments/{ID}` request changes the license assignment to a license whose users would exceed the license’s user hard limit Details: `Adding this environment to the specified license would exceed the license’s user limit.`
400	`REQUEST_FAILED`	None	Message: `PRODUCTION environments must have status updated to DELETE_PENDING before deletion.` When and details When: A `DELETE /environments/{ID}` request targets a `PRODUCTION` environment that does not have `DELETE_PENDING` status Details: None.
400	`REQUEST_FAILED`	None	Message: Cannot demote PRODUCTION environment without the soft delete override feature flag on: P14C-59480_environment_soft_delete_override_allow_demotion When and details When: A `PUT /environments/{ID}` or `PUT /environments/{ID}/type` request demotes a `PRODUCTION` environment to `SANDBOX` (allowed only when the soft delete demotion override feature flag is enabled for the organization) Details: None.
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `POST` or `PUT /environments` request supplies an `icon` value that is not a well-formed URL Details: `Invalid icon url`
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: `GET /environments` uses a negative `limit` value Details: `Limit parameter must be at least one.`
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: `GET /environments` uses an `order` value other than `name` or `created` Details: `A query string parameter or value is not valid for this request`, with a `supportedAttributes` inner error listing `name` and `created`
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: `GET /environments` uses a `cursor` value that cannot be resolved, such as a marker that is malformed or names a deleted environment Details: `Cannot find pagination marker, invalid format or environment from where to page has been deleted.`
400	`REQUEST_FAILED`	`INVALID_FILTER`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: `GET /environments` uses a `filter` expression with an unsupported operator, an attribute that does not support filtering, or an invalid value Details: The detail target is `operator` (message `The filter operator was invalid or not supported`, with a `supportedOperators` inner error), `attribute` (message `The filter attribute was invalid or does not support filtering`, with a `supportedAttributes` inner error), or `value` (message `The value provided is invalid`)
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `orgmgt:read:environment` permission (`GET` operations), the `orgmgt:create:environment` permission (`POST /environments`), the `orgmgt:update:environment` permission (`PUT /environments/{ID}`), the `orgmgt:promote:environment` permission (`PUT /environments/{ID}/type`), or the `orgmgt:delete:environment` permission (`DELETE /environments/{ID}` and `PUT /environments/{ID}/status`) Details: None.
403	`ACCESS_FAILED`	`INSUFFICIENT_PERMISSIONS`	Message: `The request could not be completed. You do not have access to this resource.` When and details When: The actor has the required permission but no role assignment whose scope covers the target organization or environment (creating an environment requires an organization‑level scope; all other operations accept an organization‑level or environment‑level scope) Details: `The actor attempting to perform the request is not authorized.`
404	`NOT_FOUND`	None	Message: `Unable to find environment with ID: '<id>'` When and details When: `GET`, `PUT`, or `DELETE /environments/{ID}`, or a `PUT /environments/{ID}/type` or `/status` request, references an environment that does not exist Details: None.
429	`REQUEST_LIMITED`	None	Message: `The request could not be completed. A rate or quota limit was reached. Please try again later.` When and details When: A `POST /environments` request includes PingOne DaVinci in `billOfMaterials.products` and the organization exceeded its rate for creating environments with DaVinci Details: None.
500	`UNEXPECTED_ERROR`	None	Message: Describes the underlying failure, such as `Failed to delete name encountering error in batch in Cassandra: <message>`. For unhandled internal failures, `There was an unexpected error with the service. Please try again later.` When and details When: An environment operation fails unexpectedly while persisting or deleting the environment Details: None.

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [<property> must not be null]

When and details

When: A POST or PUT /environments request omits one of the required properties: name, type, or region

Details: Target is the omitted property.

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT /environments request supplies a name that does not match the object name rules, or a description that does not match the description character rules

Details: must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens for name, or must contain only Unicode letters, marks, numbers, spaces, or punctuation (except $, +, <, =, >, ^, `, |, ~) for description, for example:

Validation Error : [name must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens]

400

INVALID_DATA

OUT_OF_RANGE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT /environments request supplies a name longer than 256 characters, or a description longer than 1024 characters

Details: size must be between 1 and 256 for name, or size must be between 1 and 1024 for description, with rangeMinimumValue and rangeMaximumValue inner errors, for example Validation Error : [name size must be between 1 and 256].

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT /environments request, a PUT /environments/{ID}/type request, or a PUT /environments/{ID}/status request supplies a type or status value that is not one of the allowed values

Details: must be one of the values: SANDBOX, PREPRODUCTION, or PRODUCTION for type, or must be one of the values: ACTIVE or DELETE_PENDING for status, for example Validation Error : [type must be one of the values: SANDBOX, PREPRODUCTION, or PRODUCTION]. Setting type to PREPRODUCTION when the P14C-72721_allow_preproduction_environment_type feature flag is off for the organization returns the same top‑level code and message, with the detail The PREPRODUCTION environment type requires enabling the Feature Flag: P14C-72721_allow_preproduction_environment_type (target type)

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /environments request creates an environment with a name that already exists in the organization, or a PUT /environments/{ID} request renames the environment to one that does

Details: Environment already exists with the name '<name>'

400

INVALID_DATA

REQUIRED_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /environments request from an actor whose access token does not identify an organization omits organization.id from the request body

Details: For actors without an associated organization, organization must be specified in the request body.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /environments request specifies a region that is not supported by the endpoint that received the request

Details: Environment cannot be created in specified region by this service endpoint., with an allowedValues inner error listing the regions supported by the endpoint.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT /environments request, or a PUT /environments/{ID}/status request setting status to ACTIVE, specifies a license.id that fails one of the license assignment validations

Details: One of License specified to be assigned to this environment does not exist., License specified to be assigned to this environment does not support environment region., License specified to be assigned to this environment does not support production environments., does not support assigning a Pingone account id, License specified to be assigned to this environment cannot be assigned to additional environments., The License specified has a start date in the future and cannot be used yet., or Cannot provision license of package <licensePackage>.

400

INVALID_DATA

REQUIRED_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /environments request specifies neither license.id nor license.package, and the organization has no licenses that can be assigned to additional environments, or has more than one, so the request must specify a license

Details: No active licenses exist for organization that can be assigned to additional environments. or Multiple licenses are active for organization, so license must be specified in request.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT /environments/{ID} request assigns a different license to an environment that has DELETE_PENDING status

Details: A license cannot be assigned to an environment with status DELETE_PENDING

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT /environments/{ID}/status request sets status to ACTIVE without specifying a license.id

Details: licenseId is required when setting the status to ACTIVE.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT /environments/{ID}/status request targets an environment whose type is not PRODUCTION (allowed only when the soft delete demotion override feature flag is enabled for the organization)

Details: Cannot update status on environments other than PRODUCTION.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT /environments/{ID}/status request sets status to DELETE_PENDING when the organization has reached its maximum number of soft deleted environments (100)

Details: Environment cannot be soft deleted as the maximum number of soft deleted environments has been reached.

400

INVALID_DATA

None

Message: Soft Deleted Environment cannot be hard deleted until <hardDeleteAllowedAt>

When and details

When: A DELETE /environments/{ID} request hard deletes a PRODUCTION environment whose DELETE_PENDING waiting period has not elapsed

Details: None.

400

INVALID_REQUEST

None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A request body is missing or cannot be parsed as JSON, or an environment ID in the request path cannot be parsed as a UUID

Details: None. For an unparseable path UUID the top-level code stays INVALID_REQUEST but the message reads The request could not be completed. One or more validation errors were in the request.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A DELETE /environments/{ID} request, or a PUT /environments/{ID}/status request setting DELETE_PENDING, targets the environment that the actor belongs to

Details: Cannot delete an Environment (ID: '<id>') that you as a user belong to.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A PUT /environments/{ID} request changes the license assignment to a license whose users would exceed the license’s user hard limit

Details: Adding this environment to the specified license would exceed the license’s user limit.

400

REQUEST_FAILED

None

Message: PRODUCTION environments must have status updated to DELETE_PENDING before deletion.

When and details

When: A DELETE /environments/{ID} request targets a PRODUCTION environment that does not have DELETE_PENDING status

Details: None.

400

REQUEST_FAILED

None

Message:

Cannot demote PRODUCTION environment without the soft delete override feature flag on: P14C-59480_environment_soft_delete_override_allow_demotion

When and details

When: A PUT /environments/{ID} or PUT /environments/{ID}/type request demotes a PRODUCTION environment to SANDBOX (allowed only when the soft delete demotion override feature flag is enabled for the organization)

Details: None.

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST or PUT /environments request supplies an icon value that is not a well-formed URL

Details: Invalid icon url

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request.

When and details

When: GET /environments uses a negative limit value

Details: Limit parameter must be at least one.

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: GET /environments uses an order value other than name or created

Details: A query string parameter or value is not valid for this request, with a supportedAttributes inner error listing name and created

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request.

When and details

When: GET /environments uses a cursor value that cannot be resolved, such as a marker that is malformed or names a deleted environment

Details: Cannot find pagination marker, invalid format or environment from where to page has been deleted.

400

REQUEST_FAILED

INVALID_FILTER

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: GET /environments uses a filter expression with an unsupported operator, an attribute that does not support filtering, or an invalid value

Details: The detail target is operator (message The filter operator was invalid or not supported, with a supportedOperators inner error), attribute (message The filter attribute was invalid or does not support filtering, with a supportedAttributes inner error), or value (message The value provided is invalid)

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the orgmgt:read:environment permission (GET operations), the orgmgt:create:environment permission (POST /environments), the orgmgt:update:environment permission (PUT /environments/{ID}), the orgmgt:promote:environment permission (PUT /environments/{ID}/type), or the orgmgt:delete:environment permission (DELETE /environments/{ID} and PUT /environments/{ID}/status)

Details: None.

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The actor has the required permission but no role assignment whose scope covers the target organization or environment (creating an environment requires an organization‑level scope; all other operations accept an organization‑level or environment‑level scope)

Details: The actor attempting to perform the request is not authorized.

404

NOT_FOUND

None

Message: Unable to find environment with ID: '<id>'

When and details

When: GET, PUT, or DELETE /environments/{ID}, or a PUT /environments/{ID}/type or /status request, references an environment that does not exist

Details: None.

429

REQUEST_LIMITED

None

Message: The request could not be completed. A rate or quota limit was reached. Please try again later.

When and details

When: A POST /environments request includes PingOne DaVinci in billOfMaterials.products and the organization exceeded its rate for creating environments with DaVinci

Details: None.

500

UNEXPECTED_ERROR

None

Message: Describes the underlying failure, such as Failed to delete name encountering error in batch in Cassandra: <message>. For unhandled internal failures, There was an unexpected error with the service. Please try again later.

When and details

When: An environment operation fails unexpectedly while persisting or deleting the environment

Details: None.

PingOne Platform APIs

Environments

Environment types

Environments and product types

Roles and environments

Assigning admin roles and permissions to this service

Deleting environments

Restoring environments

Environments data model

Filtering data

Environment events generated

Response codes

Environment errors