PingOne Platform APIs

Update Group

 

PUT {{apiPath}}/environments/{{envID}}/groups/{{groupID}}

The PUT {{apiPath}}/environments/{{envID}}/groups/{{groupID}} operation updates one group.

You cannot update population.id with this operation. This property is read-only after a group is created. For more information, refer to Creating groups.

Prerequisites

  • Refer to Groups for important overview information.

Request Model

Refer to the Groups data model for full property descriptions.

Property Type Required?

customData

JSON blob

Optional

description

String

Optional

externalId

String

Optional

name

String

Required

userFilter

String

Optional

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
"name": "MyGroupName1",
"description": "This is a group for testing.",
"externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
"customData": {
    "groupOwnwer": "Bill Sample",
    "securityGroup": true
    },
"userFilter": "title eq \"Manager\""
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff --request PUT '{{apiPath}}/environments/{{envID}}/groups/{{groupID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
"name": "MyGroupName1",
"description": "This is a group for testing.",
"externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
"customData": {
    "groupOwnwer": "Bill Sample",
    "securityGroup": true
    },
"userFilter": "title eq \"Manager\""
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/groups/{{groupID}}")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Put);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"""name"": ""MyGroupName1""," + "\n" +
@"""description"": ""This is a group for testing.""," + "\n" +
@"""externalId"": ""cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain""," + "\n" +
@"""customData"": {" + "\n" +
@"    ""groupOwnwer"": ""Bill Sample""," + "\n" +
@"    ""securityGroup"": true" + "\n" +
@"    }," + "\n" +
@"""userFilter"": ""title eq \""Manager\""""" + "\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}}/groups/{{groupID}}"
  method := "PUT"

  payload := strings.NewReader(`{
"name": "MyGroupName1",
"description": "This is a group for testing.",
"externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
"customData": {
    "groupOwnwer": "Bill Sample",
    "securityGroup": true
    },
"userFilter": "title eq \"Manager\""
}`)

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

{
"name": "MyGroupName1",
"description": "This is a group for testing.",
"externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
"customData": {
    "groupOwnwer": "Bill Sample",
    "securityGroup": true
    },
"userFilter": "title eq \"Manager\""
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\"name\": \"MyGroupName1\",\n\"description\": \"This is a group for testing.\",\n\"externalId\": \"cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain\",\n\"customData\": {\n    \"groupOwnwer\": \"Bill Sample\",\n    \"securityGroup\": true\n    },\n\"userFilter\": \"title eq \\\"Manager\\\"\"\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/groups/{{groupID}}")
  .method("PUT", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/environments/{{envID}}/groups/{{groupID}}",
  "method": "PUT",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "name": "MyGroupName1",
    "description": "This is a group for testing.",
    "externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
    "customData": {
      "groupOwnwer": "Bill Sample",
      "securityGroup": true
    },
    "userFilter": "title eq \"Manager\""
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'PUT',
  'url': '{{apiPath}}/environments/{{envID}}/groups/{{groupID}}',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "name": "MyGroupName1",
    "description": "This is a group for testing.",
    "externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
    "customData": {
      "groupOwnwer": "Bill Sample",
      "securityGroup": true
    },
    "userFilter": "title eq \"Manager\""
  })

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

url = "{{apiPath}}/environments/{{envID}}/groups/{{groupID}}"

payload = json.dumps({
  "name": "MyGroupName1",
  "description": "This is a group for testing.",
  "externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
  "customData": {
    "groupOwnwer": "Bill Sample",
    "securityGroup": True
  },
  "userFilter": "title eq \"Manager\""
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{accessToken}}'
}

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

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/environments/{{envID}}/groups/{{groupID}}');
$request->setMethod(HTTP_Request2::METHOD_PUT);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n"name": "MyGroupName1",\n"description": "This is a group for testing.",\n"externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",\n"customData": {\n    "groupOwnwer": "Bill Sample",\n    "securityGroup": true\n    },\n"userFilter": "title eq \\"Manager\\""\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}}/groups/{{groupID}}")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Put.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "name": "MyGroupName1",
  "description": "This is a group for testing.",
  "externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
  "customData": {
    "groupOwnwer": "Bill Sample",
    "securityGroup": true
  },
  "userFilter": "title eq \"Manager\""
})

response = http.request(request)
puts response.read_body
let parameters = "{\n\"name\": \"MyGroupName1\",\n\"description\": \"This is a group for testing.\",\n\"externalId\": \"cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain\",\n\"customData\": {\n    \"groupOwnwer\": \"Bill Sample\",\n    \"securityGroup\": true\n    },\n\"userFilter\": \"title eq \\\"Manager\\\"\"\n}"
let postData = parameters.data(using: .utf8)

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

request.httpMethod = "PUT"
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

200 OK

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/groups/bb0756de-b2ac-412b-81d4-20d2f111fb4d"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "allUserMembers": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users?filter=memberOfGroups%5Bid%20eq%20%22bb0756de-b2ac-412b-81d4-20d2f111fb4d%22%5D"
        },
        "directUserMembers": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users?filter=memberOfGroups%5Bid%20eq%20%22bb0756de-b2ac-412b-81d4-20d2f111fb4d%22%20and%20type%20eq%20%22DIRECT%22%5D"
        },
        "allGroupMembers": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/groups?filter=memberOfGroups%5Bid%20eq%20%22bb0756de-b2ac-412b-81d4-20d2f111fb4d%22%5D"
        },
        "directGroupMembers": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/groups?filter=memberOfGroups%5Bid%20eq%20%22bb0756de-b2ac-412b-81d4-20d2f111fb4d%22%20and%20type%20eq%20%22DIRECT%22%5D"
        }
    },
    "id": "bb0756de-b2ac-412b-81d4-20d2f111fb4d",
    "environment": {
        "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
    },
    "name": "MyGroupName1",
    "description": "This is a group for testing.",
    "externalId": "cn=Some Group,ou=groups,dc=some,dc=active-directory,dc=domain",
    "customData": {
        "groupOwnwer": "Bill Sample",
        "securityGroup": true
    },
    "directMemberCounts": {
        "users": 0,
        "groups": 0
    },
    "createdAt": "2023-03-23T18:32:49.737Z",
    "updatedAt": "2023-03-23T18:33:30.256Z",
    "checkSum": "15155775465",
    "userFilter": "title eq \"Manager\""
}