Create Group

POST

groups

Create Group

curl --request POST \
  --url https://public.api.serval.com/v2/groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "userIds": [
    "<string>"
  ],
  "managerTeamId": "<string>",
  "scopedId": "<string>"
}
'

import requests

url = "https://public.api.serval.com/v2/groups"

payload = {
    "name": "<string>",
    "userIds": ["<string>"],
    "managerTeamId": "<string>",
    "scopedId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    userIds: ['<string>'],
    managerTeamId: '<string>',
    scopedId: '<string>'
  })
};

fetch('https://public.api.serval.com/v2/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://public.api.serval.com/v2/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' => '<string>',
    'userIds' => [
        '<string>'
    ],
    'managerTeamId' => '<string>',
    'scopedId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://public.api.serval.com/v2/groups"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"managerTeamId\": \"<string>\",\n  \"scopedId\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://public.api.serval.com/v2/groups")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"managerTeamId\": \"<string>\",\n  \"scopedId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/groups")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"managerTeamId\": \"<string>\",\n  \"scopedId\": \"<string>\"\n}"

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

{
  "data": {
    "id": "<string>",
    "name": "<string>",
    "organizationId": "<string>",
    "createdAt": "2025-01-15T01:30:15.000Z",
    "deletedAt": "2025-01-15T01:30:15.000Z",
    "userIds": [
      "<string>"
    ],
    "managerTeamIds": [
      "<string>"
    ],
    "scopedId": "<string>",
    "externallyManaged": true,
    "configurationTeamId": "<string>"
  }
}

Authentication and permissions

Token requirements: User-based token (OAuth) or Organization-scoped API key or Workspace-scoped API key. Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.

Credential	Access requirements
Organization-scoped API key	Create an organization-wide group: `groups:manage` Create a workspace-owned group, Create a workspace-owned group as organization admin: Unsupported
Workspace-scoped API key	Create an organization-wide group, Create a workspace-owned group as organization admin: Unsupported Create a workspace-owned group: `groups:manage`
User-based token (OAuth)	Supported, subject to permissions

Permissions joined by + are all required; or separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.

Create an organization-wide group: Omit manager_team_id.
Create a workspace-owned group: Supply manager_team_id. A workspace-scoped key must allow that workspace, must hold groups:manage (a full-access workspace key cannot), and may add only people as members.
Create a workspace-owned group as organization admin: The organization fallback requires a user identity; an organization API key cannot use it.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name

string

required

userIds

string[]

managerTeamId

string | null

When set, creates a workspace-scoped group managed by this workspace (seeded as the sole manager workspace, with a default all-members viewer entry). Unset creates an org-wide group.

scopedId

string | null

Response

200 - application/json

Success

data

data · object

Show child attributes

Create Group

curl --request POST \
  --url https://public.api.serval.com/v2/groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "userIds": [
    "<string>"
  ],
  "managerTeamId": "<string>",
  "scopedId": "<string>"
}
'

import requests

url = "https://public.api.serval.com/v2/groups"

payload = {
    "name": "<string>",
    "userIds": ["<string>"],
    "managerTeamId": "<string>",
    "scopedId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    userIds: ['<string>'],
    managerTeamId: '<string>',
    scopedId: '<string>'
  })
};

fetch('https://public.api.serval.com/v2/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://public.api.serval.com/v2/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' => '<string>',
    'userIds' => [
        '<string>'
    ],
    'managerTeamId' => '<string>',
    'scopedId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://public.api.serval.com/v2/groups"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"managerTeamId\": \"<string>\",\n  \"scopedId\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://public.api.serval.com/v2/groups")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"managerTeamId\": \"<string>\",\n  \"scopedId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/groups")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"userIds\": [\n    \"<string>\"\n  ],\n  \"managerTeamId\": \"<string>\",\n  \"scopedId\": \"<string>\"\n}"

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

{
  "data": {
    "id": "<string>",
    "name": "<string>",
    "organizationId": "<string>",
    "createdAt": "2025-01-15T01:30:15.000Z",
    "deletedAt": "2025-01-15T01:30:15.000Z",
    "userIds": [
      "<string>"
    ],
    "managerTeamIds": [
      "<string>"
    ],
    "scopedId": "<string>",
    "externallyManaged": true,
    "configurationTeamId": "<string>"
  }
}

Get started

Authentication

Endpoints

Development

Authentication and permissions

Authorizations

Body

Response

​Authentication and permissions

Authorizations

Body

Response

Authentication and permissions