---
title: "Get the groups the credential creator can see."
method: GET
path: "/api/v2/groups"
tags: ["Groups"]
---

# Get the groups the credential creator can see.

`GET /api/v2/groups`

## Request

- Base URL: `https://app.blackkitetech.com`
- URL: `https://app.blackkitetech.com/api/v2/groups`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://app.blackkitetech.com//api/v2/oauth/token`
- TypeScript: <https://skmtc.dev/blackkitetech/apis/black-kite-api/docs/api/v2/groups/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the groups visible to the user who created this credential, with the members that same user would see on GET /api/v2/users, and the role assignments they can see. Requires the "User Access Management - Read" permission. When User Access Management for groups has not been enabled for the tenant, the call is rejected before groups are read.

## Query parameters

- `page_number` integer
- `page_size` 10 | 20 | 30 | 50 | 100 | 250

## Response `200`

A bare array. Field order is GroupId, Name, Description, CreatedDate, CreatedBy, NumberOfUsers, Users, RoleAssignments.

- Group[]
  - `GroupId` integer, required: The id of the group.
  - `Name` string, required: The name of the group.
  - `Description` string, required: A short description of the group.
  - `CreatedDate` string, date-time, required: The date and time the group was created, in UTC.
  - `CreatedBy` string, required: The user who created the group.
  - `NumberOfUsers` integer, required: The length of Users.
  - `Users` GroupUser[], required: Never null. Empty when no member is visible.
    - `UserId` string, required: The profile id GET /api/v2/users returns, as a string.
    - `FullName` string, required: The full name of the user.
    - `Email` string, required: The email address of the user.
  - `RoleAssignments` GroupRoleAssignment[], required: Never null. Appended after Users. An all-ecosystems grant is a flag, not an expanded list. Cross-tenant tenant ids are not returned.
    - `RoleId` integer, required: The RoleId returned by GET /api/v2/roles.
    - `RoleName` string, required: The display name of the role.
    - `AllEcosystems` boolean, required: True when the role is assigned to all ecosystems; false when it is limited to AuthorizedEcosystems and AuthorizedCompanies.
    - `AuthorizedEcosystems` GroupEcosystem[], required: The ecosystems the role is assigned to.
      - `EcosystemId` integer, required: The id of the ecosystem.
      - `EcosystemName` string, required: The name of the ecosystem.
    - `ExcludedEcosystems` object[], required: Populated only when AllEcosystems is true.
      - `EcosystemId` integer, required: The id of the excluded ecosystem.
      - `EcosystemName` string, required: The name of the excluded ecosystem.
    - `AuthorizedCompanies` GroupCompany[], required: Empty when AllEcosystems is true.
      - `CompanyId` integer, required: The id of the company.
      - `CompanyName` string, required: The name of the company.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `default`: Failure

## Changes

- **2026-10-23** `fc42796447f4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/blackkitetech/apis/black-kite-api/changes/api/v2/groups/get.md)

---

[API](https://skmtc.dev/blackkitetech/apis/black-kite-api.md) - [All operations](https://skmtc.dev/blackkitetech/apis/black-kite-api/llms.txt) - [OpenAPI document](https://skmtc.dev/blackkitetech/apis/black-kite-api/revisions/fc42796447f4?raw)