# Groups

A group gives its grants to every member in it; list, create, rename and delete groups and set who is in them.

Ids: uuid.

- `GET /workspaces/{workspace_id}/groups` [List groups](#list-groups)
- `GET /workspaces/{workspace_id}/groups/{id}` [Read a group](#read-group)
- `POST /workspaces/{workspace_id}/groups` [Create a group](#create-group)
- `PATCH /workspaces/{workspace_id}/groups/{id}` [Rename a group](#update-group)
- `PUT /workspaces/{workspace_id}/groups/{id}/members` [Set a group's members](#update-group-members)
- `DELETE /workspaces/{workspace_id}/groups/{id}` [Delete a group](#delete-group)

## Group object

A group is a set of members who all hold the group's grants.

- `id` (uuid): The group's id.
- `name` (string): The group's name.
- `created_at` (date-time): When the group was created.
- `updated_at` (date-time): When the group last changed.
- `grants` (array of Grant): The group's grants you are shown.
- `other_grants` (boolean): True when the group holds a grant you are not shown.
- `member_count` (integer): How many members are in the group.
- `members` (array of GroupMember): Everyone in the group, name and email only, as `read-group` shows them: sent only when `fields` names it, then a list, empty for a group with no members.

## List groups

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/groups`

Preview

Returns the workspace's groups, each with its grants and how many members it has, a page at a time, oldest first. Needs `group.read`; you see the groups your reach contains.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `admin:read`, `admin:write`
- Privilege: `group.read`

Needs `group.read`. `group.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.

### Behavior

- Retry: Safe to send again
- Paging: Cursor · 1000 a page by default, up to 5000

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `name` (string): Only the group of this name: the way to find the group a refused create names as taken. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
- `limit` (integer): How many groups a page holds: 1 to 5000, 1000 by default.
  Default: `1000` · 1 to 5000
- `cursor` (string): The `next_cursor` of the previous page, with the same filters.
- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `name`, `created_at`, `updated_at`, `grants`, `other_grants`, `member_count`

Sent only when named in `fields`: `members`

### Response (200)

- `groups` (array of Group, required): The groups on this page.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor` for the next page.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `limit` is not 1 to 5000, or `cursor` cannot be read or was sent with other filters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `group.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group)
- [Create a group](https://sparklogs.com/docs/api/reference/groups.md#create-group)
- [Rename a group](https://sparklogs.com/docs/api/reference/groups.md#update-group)
- [Set a group's members](https://sparklogs.com/docs/api/reference/groups.md#update-group-members)
- [Delete a group](https://sparklogs.com/docs/api/reference/groups.md#delete-group)

### Example

List groups

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "groups": [
    {
      "id": "9a0b0000-0000-4000-8000-000000000401",
      "name": "Helpdesk Tier 1",
      "created_at": "2026-11-02T10:00:00Z",
      "updated_at": "2026-11-02T10:00:00Z",
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000503",
          "role_id": "analyst_no_raw_logs",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000101",
              "0a9e0000-0000-4000-8000-000000000105"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "member_count": 1
    },
    {
      "id": "9a0b0000-0000-4000-8000-000000000402",
      "name": "Project Engineers",
      "created_at": "2026-11-02T10:00:00Z",
      "updated_at": "2026-11-02T10:00:00Z",
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000505",
          "role_id": "engineer",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000103"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "member_count": 0
    }
  ],
  "message": "workspace groups retrieved",
  "next_cursor": null
}
```

## Read a group

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/groups/{id}`

Preview

Returns one group with everyone in it, whatever your reach, so the membership read can be sent back whole. Needs `group.read`. A group you cannot see returns 404, as one that does not exist does.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `admin:read`, `admin:write`
- Privilege: `group.read`

Needs `group.read`. `group.read` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The group's id.

### Response (200)

- `group` (GroupDetail, required): The group.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `group.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such group, or one you cannot see. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List groups](https://sparklogs.com/docs/api/reference/groups.md#list-groups)
- [Create a group](https://sparklogs.com/docs/api/reference/groups.md#create-group)
- [Rename a group](https://sparklogs.com/docs/api/reference/groups.md#update-group)
- [Set a group's members](https://sparklogs.com/docs/api/reference/groups.md#update-group-members)
- [Delete a group](https://sparklogs.com/docs/api/reference/groups.md#delete-group)

### Example

Read a group with its members

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "workspace group retrieved",
  "group": {
    "id": "9a0b0000-0000-4000-8000-000000000401",
    "name": "Helpdesk Tier 1",
    "created_at": "2026-11-02T10:00:00Z",
    "updated_at": "2026-11-02T10:00:00Z",
    "grants": [
      {
        "id": "6a170000-0000-4000-8000-000000000503",
        "role_id": "analyst_no_raw_logs",
        "scope": {
          "kind": "selected",
          "org_ids": [
            "0a9e0000-0000-4000-8000-000000000101",
            "0a9e0000-0000-4000-8000-000000000105"
          ],
          "inherited": false,
          "other_orgs": false
        }
      }
    ],
    "other_grants": false,
    "member_count": 1,
    "members": [
      {
        "user_id": "SamChenExampleUserId00000002",
        "email": "sam.chen@example.com",
        "full_name": "Sam Chen",
        "display_name": "Sam"
      }
    ]
  }
}
```

## Create a group

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/groups`

Preview

Creates a group with its grants and, optionally, its members. Needs `group.write`, and `grant.write` over each grant it names; a group with no grants needs `group.write` over every organization. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `group.write`

Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Read before sending again
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Request body

- `name` (string, required): The group's name. Cleaned, as every name is. Required.
  at most 128 characters
- `grants` (array of GrantRequest or null): The group's grants. A group with none needs `group.write` over every organization.
- `user_ids` (array of string or null): Members to put in the group, each one you are shown.

### Response (200)

- `id` (uuid, required): The id of the row the call created or changed.
- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `name` is empty, a member in `user_ids` is not one you can see, or a grant names a role the workspace does not have, or a malformed scope. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | A grant names no role. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `name` is longer than 128 characters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | A grant reaches beyond what you may grant, or the group has no grants and you do not hold `group.write` over every organization. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 409 | `APP_API_ERR_ALREADY_TAKEN` | Another group in the workspace has this name; `parameter` is `name`. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List groups](https://sparklogs.com/docs/api/reference/groups.md#list-groups)
- [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group)
- [Rename a group](https://sparklogs.com/docs/api/reference/groups.md#update-group)
- [Set a group's members](https://sparklogs.com/docs/api/reference/groups.md#update-group-members)
- [Delete a group](https://sparklogs.com/docs/api/reference/groups.md#delete-group)

### Example

Create the helpdesk group

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grants": [
      {
        "role_id": "analyst_no_raw_logs",
        "scope": {
          "kind": "selected",
          "org_ids": [
            "0a9e0000-0000-4000-8000-000000000101",
            "0a9e0000-0000-4000-8000-000000000105"
          ]
        }
      }
    ],
    "name": "Helpdesk Tier 1",
    "user_ids": [
      "SamChenExampleUserId00000002"
    ]
  }'
```

Response (200)

```json
{
  "message": "group created",
  "id": "9a0b0000-0000-4000-8000-000000000401",
  "cache_clear_status": "ok"
}
```

## Rename a group

`PATCH https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/groups/{id}`

Preview

Renames a group. Needs `group.write` over it. A group you cannot see returns 404, as one that does not exist does.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `group.write`

Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The group's id.

### Request body

- `name` (string, required): The new name. Cleaned, as every name is. Required.
  at most 128 characters

### Response (200)

- `id` (uuid, required): The id of the row the call created or changed.
- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `name` is empty. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `name` is longer than 128 characters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | The group holds grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such group, or one you cannot see. | No |
| 409 | `APP_API_ERR_ALREADY_TAKEN` | Another group in the workspace has this name; `parameter` is `name`. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List groups](https://sparklogs.com/docs/api/reference/groups.md#list-groups)
- [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group)
- [Create a group](https://sparklogs.com/docs/api/reference/groups.md#create-group)
- [Set a group's members](https://sparklogs.com/docs/api/reference/groups.md#update-group-members)
- [Delete a group](https://sparklogs.com/docs/api/reference/groups.md#delete-group)

### Example

Rename a group

```bash
curl -X PATCH \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Field Engineers"
  }'
```

Response (200)

```json
{
  "message": "group renamed",
  "id": "9a0b0000-0000-4000-8000-000000000402"
}
```

## Set a group's members

`PUT https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/groups/{id}/members`

Preview · Destructive

Sets who is in a group: the list sent is the whole membership, so a member left out is removed. A member added must be one your member list shows. Needs `group.write`, and the group must sit inside your own access: for each of its grants, `grant.write`, `group.write` and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`, even when the list sent changes nothing. `other_grants` and the `scope` markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404. Sending the members it already has changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `group.write`

Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The group's id.

### Request body

- `user_ids` (array of string, required): Everyone who is in the group from now on; an empty list empties it. Required.

### Response (200)

- `id` (uuid, required): The id of the row the call created or changed.
- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | `user_ids` is left out, null or not a list of strings. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A member added is not one you can see. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | You do not hold `grant.write`, `group.write` and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs `group.write` over every organization. A list that changes nothing is refused the same way. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such group, or one you cannot see. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List groups](https://sparklogs.com/docs/api/reference/groups.md#list-groups)
- [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group)
- [Create a group](https://sparklogs.com/docs/api/reference/groups.md#create-group)
- [Rename a group](https://sparklogs.com/docs/api/reference/groups.md#update-group)
- [Delete a group](https://sparklogs.com/docs/api/reference/groups.md#delete-group)

### Example

Add Alex to the helpdesk group, keeping Sam

```bash
curl -X PUT \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "SamChenExampleUserId00000002",
      "AlexRiveraExampleUserId00001"
    ]
  }'
```

Response (200)

```json
{
  "message": "group members replaced",
  "id": "9a0b0000-0000-4000-8000-000000000401",
  "cache_clear_status": "ok"
}
```

## Delete a group

`DELETE https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/groups/{id}`

Preview · Destructive

Deletes a group and its grants; its members lose what they held through it. Needs `group.write`, and the group must sit inside your own access: for each of its grants, `grant.write`, `group.write` and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`. `other_grants` and the `scope` markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404, and so does a repeat once the group is gone: treat that as done. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `group.write`

Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The group's id.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | You do not hold `grant.write`, `group.write` and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs `group.write` over every organization. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such group, or one you cannot see. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List groups](https://sparklogs.com/docs/api/reference/groups.md#list-groups)
- [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group)
- [Create a group](https://sparklogs.com/docs/api/reference/groups.md#create-group)
- [Rename a group](https://sparklogs.com/docs/api/reference/groups.md#update-group)
- [Set a group's members](https://sparklogs.com/docs/api/reference/groups.md#update-group-members)

### Example

Delete a group

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "group deleted",
  "cache_clear_status": "ok"
}
```

## Grant object

A grant gives one member, group or workspace token one role over a scope: every organization, selected organizations and everything below them, or the workspace itself.

- `id` (uuid): The grant's id; left out on a grant an invitation will become.
- `role_id` (string, required): The role the grant gives.
- `scope` (Scope, required): Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Your own grants show whole. Changing or removing a grant with `inherited` or `other_orgs` needs access over organizations you cannot see; without it the call returns 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`.

## Scope object

- `kind` (one of the values below, required): Which organizations. Required.
  - `all`: Every organization, those added later included.
  - `selected`: The organizations in `org_ids` and everything below them.
  - `workspace`: The workspace itself, no organization.
- `org_ids` (array of uuid): With selected, the topmost organizations you can see, sorted; empty otherwise. Every answer sends it. On a write, the organizations it covers: at least one with selected, none otherwise.
- `inherited` (boolean): True when one of `org_ids` sits below an organization the scope names that you cannot see. Read-only: every answer sends it, and a write ignores it.
- `other_orgs` (boolean): True when the scope covers organizations you cannot see, which are left out without an id or a count; with all, when you cannot see every organization. Read-only: every answer sends it, and a write ignores it.

## GroupMember object

- `user_id` (string, required): The member's user id.
- `email` (email, required): The member's email address.
- `full_name` (string or null, required): The member's full name.
- `display_name` (string or null, required): The name the app shows for the member.

## GroupDetail object

- `id` (uuid, required): The group's id.
- `name` (string, required): The group's name.
- `created_at` (date-time, required): When the group was created.
- `updated_at` (date-time, required): When the group last changed.
- `grants` (array of Grant, required): The group's grants you are shown.
- `other_grants` (boolean, required): True when the group holds a grant you are not shown.
- `member_count` (integer, required): How many members are in the group.
- `members` (array of GroupMember, required): Everyone in the group, name and email only, whatever your reach, so the whole membership can be sent back changed.

## GrantRequest object

- `role_id` (string, required): The role the grant gives. Required.
- `scope` (Scope, required): Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Required.

---

Source: <https://sparklogs.com/docs/api/reference/groups>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
