User Groups REST Interface

Data

For a description of user data, see Users REST Interface.

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

{ "__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:

{ "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.

  $ 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.)

  $ 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