> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Group object

> A group synced from one of your apps, the fields v1 returns, and the permissions that listing and reading groups need.

The Group object represents a group that Lumos syncs from one of your connected
[apps](https://docs.lumos.com/reference/v1/objects/app.md), such as a group in Okta. Every group belongs to exactly one app,
and its members are Lumos [users](https://docs.lumos.com/reference/v1/objects/user.md).

Groups are read-only in v1. You can list them, read one, and list its members.

```json The Group object theme={null}
{
  "id": "4d5e6f70-8192-0123-def1-234567890123",
  "app_id": "2b3c4d5e-6f70-8901-bcde-f12345678901",
  "integration_specific_id": "00g1a2b3c4d5e6f7g8h9",
  "name": "Engineering",
  "description": "Everyone in the engineering org.",
  "group_lifecycle": "synced",
  "source_app_id": "okta.com"
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the group. Always present. |
| `app_id` | string | The `id` of the [app](https://docs.lumos.com/reference/v1/objects/app.md) the group is synced from. Always present. |
| `integration_specific_id` | string or null | The group's own ID in that app, such as its Okta group ID. |
| `name` | string or null | The group's name. |
| `description` | string or null | The group's description. |
| `group_lifecycle` | string or null | `synced` or `native`. v1 returns `synced` for every group today. |
| `source_app_id` | string or null | The `app_class_id` of the integration behind the group's app, such as `okta.com`. |

`app_id` and `source_app_id` look alike but hold different things. `app_id` is the `id` of your
app, the value you pass to [Get App](https://docs.lumos.com/api-reference/v1/apps/get-app.md). `source_app_id` is the
`app_class_id` of the app's integration, which every app connected to that integration shares.

## Filtering the list

[List Groups](https://docs.lumos.com/api-reference/v1/groups/list-groups.md) returns groups sorted by name. Three filters
narrow it:

| Filter | Effect |
| - | - |
| `name` | Groups whose name contains this text. Add `exact_match=true` to match the whole name only. |
| `integration_specific_id` | Groups with this ID in their app. |
| `app_id` | Groups synced from one app. |

An `app_id` that doesn't match an app in your organization returns `404`.

## Permissions for listing and reading groups

Listing groups needs permission to read groups across your organization. Reading one group, through
[Get Group](https://docs.lumos.com/api-reference/v1/groups/get-group.md) or
[List Group Members](https://docs.lumos.com/api-reference/v1/groups/list-group-members.md), needs permission to read that
group. Of the built-in roles, Admin, Read Only Admin, App Admin, and AppStore Read Only Admin have
both, so a user with only the User role gets `403` from all three.

## Members

[List Group Members](https://docs.lumos.com/api-reference/v1/groups/list-group-members.md) returns the group's members as
[user objects](https://docs.lumos.com/reference/v1/objects/user.md), sorted by given name. The list returns results in pages
like every other v1 list, so read [Pagination](https://docs.lumos.com/reference/v1/pagination.md) before you assume that one
call returned every member.

## Endpoints

| Endpoint | Path |
| - | - |
| [List Groups](https://docs.lumos.com/api-reference/v1/groups/list-groups.md) | `GET /v1/groups` |
| [Get Group](https://docs.lumos.com/api-reference/v1/groups/get-group.md) | `GET /v1/groups/{group_id}` |
| [List Group Members](https://docs.lumos.com/api-reference/v1/groups/list-group-members.md) | `GET /v1/groups/{group_id}/users` |