Create Environment

POST {{apiPath}}/environments

The sample shows the POST /environments operation to create a new environment associated with the organization encoded in the access token. In the request body, the name, region, and type attributes are required. The value of the name attribute must be unique within the organization. The billOfMaterials attribute allows you to specify the Ping products associated with this environment.

If you set the type attribute to PRODUCTION, you cannot delete the environment until you reset the value to SANDBOX. If you have a trial license, you cannot create PRODUCTION environments or promote SANDBOX environments to PRODUCTION.

Note: If a worker application creates a new environment, that worker application is given Identity Data Admin and Client Application Developer role assignments for that environment automatically. Only the worker application can perform Identity Data Admin operations in that environment. However, the worker application can give the same role assignment to another user or another worker application. Additionally, if the worker application doesn't have the Environment Admin role assigned for the Organization, the worker app is also assigned the Environment Admin role for the new environment. For more information about roles, see Roles.

Warning: Access to a worker application's client secret requires having a superset of the worker application's role assignments. Initially, the worker application is granted all of the role assignments of the admin (or worker app) that created it, which gives the admin (or any other admin with a superset of those role assignments) access to the worker application's secret.

However, if the worker application ever gains new role assignments (for example, by creating a new environment and being granted role assignments to cover the new environment), then this can mean that the admin who originally created the worker application can no longer access its secret. This can happen when the admin roles aren't a superset of the new role assignments for the worker application.

You can address this condition by ensuring that when an environment is created by a worker application, that worker application grants any newly received role assignments for that environment to any admins who need access to the worker application's secret. For example:

Assume there's an admin who always has full access to all environments in an Organization. This admin already has Organization Admin and Environment Admin role assignments at the Organization level. Assume as well, there's a worker application that occasionally may create new environments. To ensure this admin maintains full access to the new environments created by the worker app, as well as access to the worker application's client secret, an environment-creation script might look like this:

1. The worker application creates a new environment (POST {{apiPath}}/environments).
2. The worker application creates an Identity Data Admin role assignment for the admin, scoped to the newly created environment (POST {{apiPath}}/users/<AdminUserID>/roleAssignments).
3. The worker application creates a Client Application Developer role assignment for the admin user (POST {{apiPath}}/users/<AdminUserID>/roleAssignments).

See the the Administrator Permissions and Role Assignments section in the PingOne Developer Guide for more information.

Prerequisites

• See Environments for important overview information.

• Use Read all licenses to retrieve a list of all license IDs associated with the organization and select the specific environment's licenseID for the body. For more information, see Licenses.

• Administrator permissions and role assignments

For property descriptions, see Environments data model.

Caution: For the region property, if your environments use the AP region designation (api.pingone.asia domain) for Asia-Pacific countries, be aware that this region does not support the migration of PingID customers (or the PingID product) to the PingOne platform. To get PingID platform support for your Asia-Pacific environments, use the AU region designation (api.pingone.com.au domain) when creating your environments.

Request Body

{"name"=>"New-Env_{{$timestamp}}", "description"=>"New environment description", "type"=>"SANDBOX", "region"=>"NA", "icon"=>"https://example.com/icons/environment.jpg", "billOfMaterials"=>{"products"=>[{"type"=>"PING_ONE_BASE", "description"=>"New environment product description", "console"=>{"href"=>"https://example.com"}}]}, "license"=>{"id"=>"{{licenseID}}"}}

RESPONSES

status: Created

{"_links":{"self":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"},"organization":{"href":"https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda"},"license":{"href":"https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda/licenses/3f06970a-3235-46cb-b46f-cf6dfee2bb84"},"populations":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/populations"},"users":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users"},"applications":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/applications"},"activities":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/activities"},"branding":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/branding"},"resources":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/resources"},"passwordPolicies":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/passwordPolicies"},"userActivities":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/userActivities"},"signOnPolicies":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/signOnPolicies"},"keys":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/keys"},"templates":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/templates"},"notificationsSettings":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/notificationsSettings"},"schemas":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/schemas"},"gateways":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/gateways"},"capabilities":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/capabilities"},"activeIdentityCounts":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/activeIdentityCounts"},"propagation/plans":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/propagation/plans"},"propagation/stores":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/propagation/stores"},"propagation/revisions/id:latest":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/propagation/revisions/id:latest"},"billOfMaterials":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/billOfMaterials"}},"id":"abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6","name":"New-Env_1705684982","description":"New environment description","organization":{"id":"bed432e6-676a-4ebe-b5a5-6b3b54e46bda"},"type":"SANDBOX","region":"NA","createdAt":"2024-01-19T17:23:01.796Z","updatedAt":"2024-01-19T17:23:01.796Z","license":{"id":"3f06970a-3235-46cb-b46f-xxxxxxxxxxxx"},"billOfMaterials":{"products":[{"id":"cb7a53e5-b413-4134-8216-d846abe891b8","type":"PING_ONE_BASE","description":"New environment product description","console":{"href":"https://example.com"}}],"createdAt":"2024-01-19T17:23:01.808Z","updatedAt":"2024-01-19T17:23:01.808Z"},"icon":"https://example.com/icons/environment.jpg"}