Create a group

curl --request POST \
  --url https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Finance approvers",
  "memberIds": [
    "e3553bc1-5e20-4e17-b22a-a796fda0aa99"
  ],
  "description": "Approves payments above R$ 10,000"
}
'

import requests

url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups"

payload = {
    "name": "Finance approvers",
    "memberIds": ["e3553bc1-5e20-4e17-b22a-a796fda0aa99"],
    "description": "Approves payments above R$ 10,000"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Finance approvers',
    memberIds: ['e3553bc1-5e20-4e17-b22a-a796fda0aa99'],
    description: 'Approves payments above R$ 10,000'
  })
};

fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Finance approvers',
    'memberIds' => [
        'e3553bc1-5e20-4e17-b22a-a796fda0aa99'
    ],
    'description' => 'Approves payments above R$ 10,000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups"

	payload := strings.NewReader("{\n  \"name\": \"Finance approvers\",\n  \"memberIds\": [\n    \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\"\n  ],\n  \"description\": \"Approves payments above R$ 10,000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Finance approvers\",\n  \"memberIds\": [\n    \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\"\n  ],\n  \"description\": \"Approves payments above R$ 10,000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Finance approvers\",\n  \"memberIds\": [\n    \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\"\n  ],\n  \"description\": \"Approves payments above R$ 10,000\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "8ae5ee60-6ebe-4d85-a056-8c1387763478",
  "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "name": "Finance approvers",
  "memberIds": [
    "e3553bc1-5e20-4e17-b22a-a796fda0aa99"
  ],
  "status": "ACTIVE",
  "description": "Approves payments above R$ 10,000",
  "createdBy": "f1235202-71e0-49ef-a8ba-939b8d3ec945",
  "updatedBy": "f1235202-71e0-49ef-a8ba-939b8d3ec945",
  "createdAt": "2026-10-02T13:27:41.512Z",
  "updatedAt": "2026-10-09T17:05:12.034Z"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "GROUP_NAME_ALREADY_EXISTS",
  "origin": "IDENTITY",
  "message": "A group with this name already exists in this organization"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "GROUP_MEMBER_NOT_IN_ORGANIZATION",
  "origin": "IDENTITY",
  "message": "All group members must be users of this organization"
}

POST

realms

{realmId}

organizations

{organizationId}

groups

Create a group

curl --request POST \
  --url https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Finance approvers",
  "memberIds": [
    "e3553bc1-5e20-4e17-b22a-a796fda0aa99"
  ],
  "description": "Approves payments above R$ 10,000"
}
'

import requests

url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups"

payload = {
    "name": "Finance approvers",
    "memberIds": ["e3553bc1-5e20-4e17-b22a-a796fda0aa99"],
    "description": "Approves payments above R$ 10,000"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Finance approvers',
    memberIds: ['e3553bc1-5e20-4e17-b22a-a796fda0aa99'],
    description: 'Approves payments above R$ 10,000'
  })
};

fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Finance approvers',
    'memberIds' => [
        'e3553bc1-5e20-4e17-b22a-a796fda0aa99'
    ],
    'description' => 'Approves payments above R$ 10,000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups"

	payload := strings.NewReader("{\n  \"name\": \"Finance approvers\",\n  \"memberIds\": [\n    \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\"\n  ],\n  \"description\": \"Approves payments above R$ 10,000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Finance approvers\",\n  \"memberIds\": [\n    \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\"\n  ],\n  \"description\": \"Approves payments above R$ 10,000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/groups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Finance approvers\",\n  \"memberIds\": [\n    \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\"\n  ],\n  \"description\": \"Approves payments above R$ 10,000\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "8ae5ee60-6ebe-4d85-a056-8c1387763478",
  "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "name": "Finance approvers",
  "memberIds": [
    "e3553bc1-5e20-4e17-b22a-a796fda0aa99"
  ],
  "status": "ACTIVE",
  "description": "Approves payments above R$ 10,000",
  "createdBy": "f1235202-71e0-49ef-a8ba-939b8d3ec945",
  "updatedBy": "f1235202-71e0-49ef-a8ba-939b8d3ec945",
  "createdAt": "2026-10-02T13:27:41.512Z",
  "updatedAt": "2026-10-09T17:05:12.034Z"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "GROUP_NAME_ALREADY_EXISTS",
  "origin": "IDENTITY",
  "message": "A group with this name already exists in this organization"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "GROUP_MEMBER_NOT_IN_ORGANIZATION",
  "origin": "IDENTITY",
  "message": "All group members must be users of this organization"
}

Every member must be an active user of the organization. The group is created ACTIVE.

Path Parameters

realmId

string<uuid>

required

ID of your realm.

Format: UUID

organizationId

string<uuid>

required

ID of the organization that will own the group.

Format: UUID

Body

application/json

name

string

required

Name of the group. Must be unique within the organization, archived groups included; leading and trailing spaces are removed.

Required string length: 1 - 80

Example:

"Finance approvers"

memberIds

string<uuid>[]

required

IDs of the users in the group, without repetitions. Each one must be an active user of the organization.

Format: UUID

Example: ["e3553bc1-5e20-4e17-b22a-a796fda0aa99","61a1505a-7516-4f5b-8491-e8f8cbfd1083"]

Required array length: 1 - 100 elements

description

string

Optional description of the group.

Maximum string length: 500

Example:

"Approves payments above R$ 10,000"

Response

Successful response

A group: a named set of users of one organization, used as an approver in business policies.

string<uuid>

required

ID of the group.

Example:

"8ae5ee60-6ebe-4d85-a056-8c1387763478"

realm

string<uuid>

required

ID of the realm the group belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organization

string<uuid>

required

ID of the organization the group belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

name

string

required

Name of the group, unique within the organization (archived groups included).

Example:

"Finance approvers"

memberIds

string[]

required

IDs of the users in the group, in the order they were added.

Example: ["e3553bc1-5e20-4e17-b22a-a796fda0aa99"]

status

enum<string>

required

ACTIVE groups can be changed and used as approvers. ARCHIVED groups can still be read by ID, but are hidden from the list, can't be changed and can't be used as approvers. Archiving is permanent.

Available options:

ACTIVE,

ARCHIVED

Example:

"ACTIVE"

description

string

Description of the group. Omitted, or empty, when the group has none.

Example:

"Approves payments above R$ 10,000"

createdBy

string

ID of the user or API client that created the group. May be absent on older groups.

Example:

"f1235202-71e0-49ef-a8ba-939b8d3ec945"

updatedBy

string

ID of the user or API client that last changed the group. May be absent on older groups.

Example:

"f1235202-71e0-49ef-a8ba-939b8d3ec945"

createdAt

string<date-time>

When the group was created.

Example:

"2026-10-02T13:27:41.512Z"

updatedAt

string<date-time>

When the group last changed.

Example:

"2026-10-09T17:05:12.034Z"

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

Create a group

Path Parameters

Body

Response