PingOne Platform APIs

Create Custom Admin Role

   

POST {{apiPath}}/environments/{{envID}}/roles

The POST {{apiPath}}/environment/{{envID}}/roles request creates a new custom role with the permissions specified in the request body. This request requires at least one permission ID in the permissions property list.

To see the permission IDs associated with all PingOne predefined and custom roles in the specified environment, you can run the Read All Custom Admin Roles endpoint. The response idenifies the roles and their permissions, providing permission descriptions and the permission IDs. You can also check the PingOne Role Permissions table to see the PingOne predefined roles and their permissions.

Refer to PingOne Permissions by Identifier for all permissions and their descriptions.

Request Model

Refer to Custom role data model for full property descriptions.

Property Type Required?

applicableTo

String[]

Required

canBeAssignedByRoles

Object

Required

description

String

Optional

name

String

Required

permissions

String

Required

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
"name" : "Custom_Role_D",
"description" : "Custom Role for something",
"applicableTo" : ["ENVIRONMENT"],
"canBeAssignedBy": [
      {
          "id" : "{{envAdmRole}}"
      }
],
"permissions" : [
   {
     "id": "permissions:read:userRoleAssignments"
    }
]
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/environments/{{envID}}/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
"name" : "Custom_Role_D",
"description" : "Custom Role for something",
"applicableTo" : ["ENVIRONMENT"],
"canBeAssignedBy": [
      {
          "id" : "{{envAdmRole}}"
      }
],
"permissions" : [
   {
     "id": "permissions:read:userRoleAssignments"
    }
]
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/roles")
{
  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"" : ""Custom_Role_D""," + "\n" +
@"""description"" : ""Custom Role for something""," + "\n" +
@"""applicableTo"" : [""ENVIRONMENT""]," + "\n" +
@"""canBeAssignedBy"": [" + "\n" +
@"      {" + "\n" +
@"          ""id"" : ""{{envAdmRole}}""" + "\n" +
@"      }" + "\n" +
@"]," + "\n" +
@"""permissions"" : [" + "\n" +
@"   {" + "\n" +
@"     ""id"": ""permissions:read:userRoleAssignments""" + "\n" +
@"    }" + "\n" +
@"]" + "\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/{{envID}}/roles"
  method := "POST"

  payload := strings.NewReader(`{
"name" : "Custom_Role_D",
"description" : "Custom Role for something",
"applicableTo" : ["ENVIRONMENT"],
"canBeAssignedBy": [
      {
          "id" : "{{envAdmRole}}"
      }
],
"permissions" : [
   {
     "id": "permissions:read:userRoleAssignments"
    }
]
}`)

  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/{{envID}}/roles HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
"name" : "Custom_Role_D",
"description" : "Custom Role for something",
"applicableTo" : ["ENVIRONMENT"],
"canBeAssignedBy": [
      {
          "id" : "{{envAdmRole}}"
      }
],
"permissions" : [
   {
     "id": "permissions:read:userRoleAssignments"
    }
]
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\"name\" : \"Custom_Role_D\",\n\"description\" : \"Custom Role for something\",\n\"applicableTo\" : [\"ENVIRONMENT\"],\n\"canBeAssignedBy\": [\n      {\n          \"id\" : \"{{envAdmRole}}\"\n      }\n],\n\"permissions\" : [\n   {\n     \"id\": \"permissions:read:userRoleAssignments\"\n    }\n]\n}\n");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/roles")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/environments/{{envID}}/roles",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "name": "Custom_Role_D",
    "description": "Custom Role for something",
    "applicableTo": [
      "ENVIRONMENT"
    ],
    "canBeAssignedBy": [
      {
        "id": "{{envAdmRole}}"
      }
    ],
    "permissions": [
      {
        "id": "permissions:read:userRoleAssignments"
      }
    ]
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/environments/{{envID}}/roles',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "name": "Custom_Role_D",
    "description": "Custom Role for something",
    "applicableTo": [
      "ENVIRONMENT"
    ],
    "canBeAssignedBy": [
      {
        "id": "{{envAdmRole}}"
      }
    ],
    "permissions": [
      {
        "id": "permissions:read:userRoleAssignments"
      }
    ]
  })

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

url = "{{apiPath}}/environments/{{envID}}/roles"

payload = json.dumps({
  "name": "Custom_Role_D",
  "description": "Custom Role for something",
  "applicableTo": [
    "ENVIRONMENT"
  ],
  "canBeAssignedBy": [
    {
      "id": "{{envAdmRole}}"
    }
  ],
  "permissions": [
    {
      "id": "permissions:read:userRoleAssignments"
    }
  ]
})
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/{{envID}}/roles');
$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" : "Custom_Role_D",\n"description" : "Custom Role for something",\n"applicableTo" : ["ENVIRONMENT"],\n"canBeAssignedBy": [\n      {\n          "id" : "{{envAdmRole}}"\n      }\n],\n"permissions" : [\n   {\n     "id": "permissions:read:userRoleAssignments"\n    }\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/{{envID}}/roles")

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": "Custom_Role_D",
  "description": "Custom Role for something",
  "applicableTo": [
    "ENVIRONMENT"
  ],
  "canBeAssignedBy": [
    {
      "id": "{{envAdmRole}}"
    }
  ],
  "permissions": [
    {
      "id": "permissions:read:userRoleAssignments"
    }
  ]
})

response = http.request(request)
puts response.read_body
let parameters = "{\n\"name\" : \"Custom_Role_D\",\n\"description\" : \"Custom Role for something\",\n\"applicableTo\" : [\"ENVIRONMENT\"],\n\"canBeAssignedBy\": [\n      {\n          \"id\" : \"{{envAdmRole}}\"\n      }\n],\n\"permissions\" : [\n   {\n     \"id\": \"permissions:read:userRoleAssignments\"\n    }\n]\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/roles")!,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/roles/d94a5b8c-5391-4cd6-b350-9eb2b082b5b5"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        }
    },
    "id": "d94a5b8c-5391-4cd6-b350-9eb2b082b5b5",
    "name": "Custom_Role_D",
    "description": "Custom Role for something",
    "applicableTo": [
        "ENVIRONMENT"
    ],
    "permissions": [
        {
            "id": "permissions:read:userRoleAssignments"
        }
    ],
    "environment": {
        "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
    },
    "type": "CUSTOM",
    "canBeAssignedBy": [
        {
            "id": "29ddce68-cd7f-4b2a-b6fc-f7a19553b496"
        }
    ]
}