List Groups - Serval Documentation

GET

groups

List Groups

curl --request GET \
  --url https://public.api.serval.com/v2/groups \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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>"
    }
  ],
  "nextPageToken": "<string>"
}

Authentication and permissions

Token requirements: User-based token (OAuth) or Organization-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	`groups:manage`
Team-scoped API key	Unsupported
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. Team keys must allow every team checked by the request. OAuth access depends on the user’s roles and resource access.

Read groups: Group visibility rules still apply. A team filter does not change the organization authorization check.

Authorizations

Authorization

string

header

required

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

Query Parameters

pageSize

integer<int32>

Maximum number of results to return. Default is 100, maximum is 10000.

pageToken

string

Token for pagination. Leave empty for the first request.

userId

string

Filter to the groups this user is a member of. Each returned group still carries its full user_ids roster, not just this user.

teamId

string

Configuration-team namespace, not manager ACL. Unset lists org-visible groups.

groupIds

string[]

Resolve only these group UUIDs and team-scoped portable IDs.

scopedIds

string[]

omitMembers

boolean

Omit the user roster when only group identity and configuration are needed.

Response

200 - application/json

Success

data

Group · object[]

The list of groups.

Show child attributes

nextPageToken

string | null

Token for retrieving the next page of results. Empty if no more results.

List Groups

curl --request GET \
  --url https://public.api.serval.com/v2/groups \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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>"
    }
  ],
  "nextPageToken": "<string>"
}

​Authentication and permissions

Authorizations

Query Parameters

Response

Authentication and permissions