---
title: User Groups REST Interface
slug: ps/help/en_us/vwaf/ag/user-groups-rest-interface
docTags: 
createdAt: 2026-08-02T10:05:42.025Z
---

## Data

For a description of user data, see [Users REST Interface](docId\:recpG0hEvJ1YMM708BXzr).

User group data essentially reflect the structure as it can be seen in the group management user interface (see [Group Management](docId\:H35EqAwFWaHKcMu3_w5_9)). For example, the rights for an application administration group look like follows:

```bash
{ "__name": "app_group_2800048cc1fc7ed5-ffd51ac6a91ed212cd3a587b0e74ce9a", "__path": "/api/af/2.0/auth/groups/app_group_2800048cc1fc7ed5-ffd51ac6a91ed212cd3a587b0e74ce9a/", "__subnodes": [], "internal": true, "name": "Application Admin for myapp", "permissions": [ { "access": "*", "category": "application", "element": "*", "element_name": "*", "name": "2800048cc1fc7ed5-ffd51ac6a91ed212cd3a587b0e74ce9a" }, { "access": "read", "category": "administration", "element": "*", "element_name": "*", "name": "*" } ] }
```

Permissions is a list of the rights that are assigned to the group. A right consists of:

- access
  In the user interface this can be none, read or read/write. In the REST interface, it’s mapped as follows:
  - none-> doesn’t exist; there simply isn’t any entry in this case
  - read-> read
  - read/write-> \*
- category
  Can either be application or administration—this reflects the topmost level in group management.
- element and element\_name
  Only exist for handlers, wizards, and selectors. All other permissions don’t have these entries.
- name
  This corresponds with the second level in the navigation tree in group management. With the category application it’s the application UUID (not the name). With the category administration it’s configuration, logging, or management.

In all entries there can also be an asterisk, which matches all rights. So, a stingrayafzeusafm Administrator, who has all rights, has:

```bash
{ "access": "*", "category": "*", "element": "*", "element_name": "*", "name": "*" }
```

## Getting a list of user groups

- Request

| Method    | GET           |
| --------- | ------------- |
| URL       | /auth/groups/ |
| Arguments | –             |

- Response

| Return code | Arguments                       | Meaning                                 |
| ----------- | ------------------------------- | --------------------------------------- |
| 200         | \[ group1, group2, ... groupN ] | list of group IDs successfully returned |
| 401         | -                               | no login                                |
| 403         | -                               | not enough rights                       |
| 500         | -                               | internal server error                   |

- Example

The following request retrieves a list of all user groups. In this case, there are the two standard groups “master\_admin” and “pci\_auditor”, plus the Application Administrator group for one application. The group name for this Application Administrator group consists of the prefix “app\_group\_” plus the internal UUID of the application.

```bash
$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/auth/groups {    "__name": "groups",    "__path": "/api/af/2.0/auth/groups/",    "__subnodes": [        "master_admin",        "pci_auditor",        "app_group_f011694d47d73578-e440fd26a125de02c57dc7efa1f1bc17"    ],    "groups": [        "master_admin",        "app_group_f011694d47d73578-e440fd26a125de02c57dc7efa1f1bc17",        "pci_auditor"    ] }
```

## Getting the data of a user group

- Request

| Method    | GET                  |
| --------- | -------------------- |
| URL       | /auth/groups/GROUPID |
| Arguments | –                    |

- Response

| Return code | Arguments      | Meaning                                         |
| ----------- | -------------- | ----------------------------------------------- |
| 200         | \{ groupdata } | dictionary of permissions successfully returned |
| 401         | -              | no login                                        |
| 403         | -              | not enough rights                               |
| 404         | -              | user group not found                            |
| 500         | -              | internal server error                           |

- Example

The following request retrieves the data of the user group "master\_admin", which is named "hyperguard Admin" in the user interface.

(In the example, the response is truncated.)

```bash
$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/auth/groups/master_admin { "__name": "master_admin", "__path": "/api/af/2.0/auth/groups/master_admin/", "__subnodes": [], "internal": true, "name": "hyperguard Admin", "permissions": [ { "access": "*", "category": "*", "element": "*", "element_name": "*", "name": "*" } ] }
```

## Adding a user group

- Request

| Method    | POST                 |
| --------- | -------------------- |
| URL       | /auth/groups/        |
| Arguments | \{ name: groupname } |

- Response

| Return code | Arguments | Meaning                                               |
| ----------- | --------- | ----------------------------------------------------- |
| 200         | groupid   | user group with the given group ID successfully added |
| 401         | -         | no login                                              |
| 403         | -         | not enough rights                                     |
| 409         | -         | malformed, conflicting, or missing data               |
| 500         | -         | internal server error                                 |

## Changing user group data

- Request

| Method    | PUT                         |
| --------- | --------------------------- |
| URL       | /auth/groups/GROUPID        |
| Arguments | \{ group\_data: groupdata } |

- Response

| Return code | Arguments | Meaning                                 |
| ----------- | --------- | --------------------------------------- |
| 200         | -         | group data successfully changed         |
| 401         | -         | no login                                |
| 403         | -         | not enough rights                       |
| 404         | -         | user group not found                    |
| 409         | -         | malformed, conflicting, or missing data |
| 500         | -         | internal server error                   |

## Deleting a user group

- Request

| Method    | DELETE               |
| --------- | -------------------- |
| URL       | /auth/groups/GROUPID |
| Arguments | –                    |

- Response

| Return code | Arguments | Meaning                         |
| ----------- | --------- | ------------------------------- |
| 200         | -         | user group successfully deleted |
| 401         | -         | no login                        |
| 403         | -         | not enough rights               |
| 404         | -         | user group not found            |
| 409         | -         | user group still contains users |
| 500         | -         | internal server error           |