Group APIs

This page describes the APIs for interacting with user groups.

Requests sent to /api/groups and other URLs under the /api/groups/ path operate on user accounts. The webserver will send StatusOK (200) on a good request, while a 400-500 status will be sent on error (depending on the error).

Note

Adding and removing users from groups is done through the user account APIs, not the group APIs. These APIs are purely for creating, deleting, and describing groups.

Data types

The APIs on this page primarily deal with group details structures. The group details structure is as follows:

{
  GID: int,		// Numeric group ID
  Name: string, // Group name
  Desc: string, // Group description
  Synced: bool	// Tracks if group is synchronized with the datastore (can usually be ignored)
}

Admin only: Adding a group

To add a new group, send a POST request to /api/groups. The body of the request should contain a structure which defines the group’s name and description, as below:

{
	"Name": "newgroup",
	"Desc": "This is the new group"
}

The server will attempt to parse the request and create the group; if successful, it will respond with a 200 status code and the GID of the new group in the body of the response.

Admin only: Deleting a group

To delete a group, send a DELETE request to /api/groups/{gid}.

Admin only: Updating group info

To modify a group’s information, send a PUT request to /api/groups/{gid}. The body of the request should contain a group details structure, as below:

{
	"GID": 3,
	"Name": "newname",
	"Desc": "this is the new description",
}

If the Name or Desc fields are excluded, the current values will be kept.

Listing all groups

To get a list of all groups on the system, send a GET request to /api/groups. The response will contain an array of group details structures:

[
    {
        "Desc": "bar",
        "GID": 1,
        "Name": "foo",
        "Synced": true
    },
    {
        "Desc": "",
        "GID": 7,
        "Name": "gravwell-users",
        "Synced": false
    },
    {
        "Desc": "",
        "GID": 8,
        "Name": "testgroup",
        "Synced": false
    }
]

Getting info about a group

Administrators or members of a particular group may get information about a particular group. Issue a GET request to /api/groups/{gid}. The response will contain the group details:

{
    "Desc": "",
    "GID": 7,
    "Name": "gravwell-users",
    "Synced": false
}

Listing users in a group

Administrators or members of a particular group may query the list of users in that group by issuing a GET request to /api/groups/{gid}/members. The response will be an array of user details structures:

[
    {
        "Admin": false,
        "Email": "joe@gravwell.io",
        "Groups": [
            {
                "Desc": "bar",
                "GID": 1,
                "Name": "foo",
                "Synced": false
            },
            {
                "Desc": "",
                "GID": 7,
                "Name": "gravwell-users",
                "Synced": false
            },
            {
                "Desc": "",
                "GID": 8,
                "Name": "testgroup",
                "Synced": false
            }
        ],
        "Locked": false,
        "Name": "Joe User",
        "Synced": false,
        "TS": "2020-08-10T14:49:30.72782227-06:00",
        "UID": 16,
        "User": "joe"
    },
    {
        "Admin": false,
        "Email": "bkeaton@example.net",
        "Groups": [
            {
                "Desc": "",
                "GID": 7,
                "Name": "gravwell-users",
                "Synced": false
            }
        ],
        "Locked": false,
        "Name": "Buster Keaton",
        "Synced": false,
        "TS": "0001-01-01T00:00:00Z",
        "UID": 17,
        "User": "buster"
    }
]