PingOne Platform APIs

Create Environment

 

POST {{apiPath}}/environments

Use the POST {{apiPath}}/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 have a trial license, you cannot create PRODUCTION environments or promote SANDBOX environments to PRODUCTION.

Prerequisites

  • Refer to Environments for important overview information.

  • Refer to Roles Management to assign roles and permissions to the environment.

  • 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, refer to Licenses.

Request Model

For property descriptions, refer to Environments data model.

Property Type Required?

billOfMaterials

Object

Optional

billOfMaterials.products[0]

Array

Optional

billOfMaterials.products[0].id

String

Required

billOfMaterials.products[0].type

String

Optional

billOfMaterials.products[0].description

String

Optional

billOfMaterials.products[0].console

String

Optional

billOfMaterials.products[0].softwareLicense.id

String

Optional

billOfMaterials.products[0].deployment.id

String

Optional

description

String

Optional

icon

String

Optional

license.id

String

Required

name

String

Required

organization.id

String

Optional

region

String

Required

type

String

Required

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
  "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}}"
  }
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/environments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
  "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}}"
  }
}'
var options = new RestClientOptions("{{apiPath}}/environments")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"  ""name"": ""New-Env_{{$timestamp}}""," + "\n" +
@"  ""description"": ""New environment description""," + "\n" +
@"  ""type"": ""SANDBOX""," + "\n" +
@"  ""region"": ""NA""," + "\n" +
@"  ""icon"": ""https://example.com/icons/environment.jpg""," + "\n" +
@"  ""billOfMaterials"": {" + "\n" +
@"    ""products"": [" + "\n" +
@"      {" + "\n" +
@"        ""type"": ""PING_ONE_BASE""," + "\n" +
@"        ""description"": ""New environment product description""," + "\n" +
@"        ""console"": {" + "\n" +
@"          ""href"": ""https://example.com""" + "\n" +
@"        }" + "\n" +
@"      }" + "\n" +
@"    ]" + "\n" +
@"  }," + "\n" +
@"  ""license"": {" + "\n" +
@"    ""id"": ""{{licenseID}}""" + "\n" +
@"  }" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/environments"
  method := "POST"

  payload := strings.NewReader(`{
  "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}}"
  }
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer {{accessToken}}")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
POST /environments HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
  "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}}"
  }
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"name\": \"New-Env_{{$timestamp}}\",\n  \"description\": \"New environment description\",\n  \"type\": \"SANDBOX\",\n  \"region\": \"NA\",\n  \"icon\": \"https://example.com/icons/environment.jpg\",\n  \"billOfMaterials\": {\n    \"products\": [\n      {\n        \"type\": \"PING_ONE_BASE\",\n        \"description\": \"New environment product description\",\n        \"console\": {\n          \"href\": \"https://example.com\"\n        }\n      }\n    ]\n  },\n  \"license\": {\n    \"id\": \"{{licenseID}}\"\n  }\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/environments",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "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}}"
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/environments',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "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}}"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{apiPath}}/environments"

payload = json.dumps({
  "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}}"
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{accessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/environments');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n  "name": "New-Env_{{$timestamp}}",\n  "description": "New environment description",\n  "type": "SANDBOX",\n  "region": "NA",\n  "icon": "https://example.com/icons/environment.jpg",\n  "billOfMaterials": {\n    "products": [\n      {\n        "type": "PING_ONE_BASE",\n        "description": "New environment product description",\n        "console": {\n          "href": "https://example.com"\n        }\n      }\n    ]\n  },\n  "license": {\n    "id": "{{licenseID}}"\n  }\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/environments")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "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}}"
  }
})

response = http.request(request)
puts response.read_body
let parameters = "{\n  \"name\": \"New-Env_{{$timestamp}}\",\n  \"description\": \"New environment description\",\n  \"type\": \"SANDBOX\",\n  \"region\": \"NA\",\n  \"icon\": \"https://example.com/icons/environment.jpg\",\n  \"billOfMaterials\": {\n    \"products\": [\n      {\n        \"type\": \"PING_ONE_BASE\",\n        \"description\": \"New environment product description\",\n        \"console\": {\n          \"href\": \"https://example.com\"\n        }\n      }\n    ]\n  },\n  \"license\": {\n    \"id\": \"{{licenseID}}\"\n  }\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/environments")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

201 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"
}