User groups

Use these methods to manage user groups and view information about them.

GET[host]/api/v2/groups

Get a list of user groups

GET[host]/api/v2/groups/{groupId}

Get user group details

POST[host]/api/v2/groups

Create a new user group

PUT[host]/api/v2/groups/{groupId}

PATCH[host]/api/v2/groups/{groupId}

Update a user group

DELETE[host]/api/v2/groups/{groupId}

Delete a user group

Get a list of user groups

Use this method to obtain a list of the available user groups.

Request

Header parameters:

  • Authorization: Bearer <access_token>

GET[host]/api/v2/groups

curl --location --request GET 'https://host.name/api/v2/groups?limit=10&offset=0' \
--header 'Authorization: Bearer <token>'

Response

A response includes an array of User Group objects providing information about the available user groups.

Get user group details

Use this method to obtain detailed information about a specified user group.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Path parameters:

groupId required

The identifier of a user group.

GET[host]/api/v2/groups/{groupId}

curl --location --request GET 'https://host.name/api/v2/groups/1' \
--header 'Authorization: Bearer <token>'

Response

A response includes a User Group object providing information about the specified user group.

Create a new user group

Use this method to create a new user group with custom permissions.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Body:

Specify the following parameters for a user group:

name string required

The name of a user group.

permissions array required

An array of string values specifying the user group permissions.

These values are case-sensitive and must be unique.

You can specify any number of permissions.

An empty array indicates that no permissions are assigned to a group.

POST[host]/api/v2/groups

curl --location --request POST 'https://host.name/api/v2/groups' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "name": "Administrators",
  "permissions": [
    "accounts.create",
    "accounts.read"
  ]
}'

Response

A response includes a User Group object providing information about the created user group.

Update a user group

Use this method to update a specified user group.

Note

Instead of the method described below, you can use a similar method that uses the HTTP verb PATCH.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Path parameters:

groupId required

The identifier of a user group.

Body:

The following field values can be updated for a specified user group:

name string

The name of a user group.

permissions array

An array of string values specifying the user group permissions.

These values are case-sensitive and must be unique.

You can specify any number of permissions.

An empty array indicates that no permissions are assigned to a group.

PUT[host]/api/v2/groups/{groupId}

curl --location --request PUT 'https://host.name/api/v2/groups/1' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "name": "Administrators",
  "permissions": [
    "accounts.create",
    "accounts.read"
  ]
}'

Response

A response includes a User Group object providing information about the user group that was updated.

Delete a user group

Use this method to delete a specified user group.

Note

After a user group is deleted, users from this group retain all their individual permissions.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Path parameters:

groupId required

The identifier of a user group.

DELETE[host]/api/v2/groups/{groupId}

curl --location --request DELETE 'https://host.name/api/v2/groups/1' \
--header 'Authorization: Bearer <token>'

Response

In case of success, no response body is returned.