Skip to main content

User group resources

Virtana Service Observability manages users as members of groups, not as individuals. To enable access, create a Virtana Service Observability group and assign one or more roles to the group. If you are using an outside identity service, create Virtana Service Observability groups that match the group names in your identity service. For more information, see Managing groups.

Resource list

Create a group

POST /v1/user-mgmt/end-user-groups

Create a new group.

Request template

An abstract preview of a JSON request to create one group.

{
  "name": "<name>",
  "cloudRoles": [ "<role>" ],
  "restrictionFilters": [ "<filter>" ]
}

Request fields

Field

Type

Required

Description

name

String

Yes

A name for the new group.

cloudRoles

Array

Yes

A list of one or more Virtana Service Observability roles. Use the internal role names, not the display names, for this field.

Internal name

Display name

read_only_user

Read Only User

user

User

key_creator

Key Creator

key_administrator

Key Administrator

manager

Manager

Virtana Service Observability adds the Delegate to Collection Zone role to each new group.

restrictionFilters

Array

No

A list of one or more restriction filters.

The syntax of a restriction filter is CollectionZoneNumber:OrganizerPath. For example, cz0:Location/Austin.

For most deployments, the value of CollectionZoneNumber is cz0. If your deployment includes multiple Collection Zones, check the URI of the organizer home page for the correct number.

Note

For the CZ Locations organizer only, the organizer name portion of OrganizerPath must be Location (singular), not Locations (plural).

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

400

Bad request. The request body is missing, malformed, or contains invalid values.

401

Unauthorized. The API key is missing or invalid.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/user-mgmt/end-user-groups \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "name": "mygroup",
  "cloudRoles": [
    "user"
  ],
  "restrictionFilters": [
    "cz0:Devices/HTTP"
  ]
}'

Response example (success)

 {}

Response example (failure)

 {
  "code": 3,
  "message": "unknown value \"\\\"mgr\\\"\" for enum zenoss.cloud.CloudRoles"
}

Get one group

GET /v1/user-mgmt/end-user-groups/{group-name}

Get a group.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

401

Unauthorized. The API key is missing or invalid.

404

Not found. The specified resource does not exist.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/user-mgmt/end-user-groups/YOUR-GROUP-NAME \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET

Response example

 {
  "name": "mygroup",
  "cloudRoles": [
    "user"
  ],
  "restrictionFilters": [
    "cz0:Devices/HTTP"
  ]
}

Update a group

PUT /v1/user-mgmt/end-user-groups/{group-name}

Update an existing group.

Request fields

Update requests use the same fields as create requests. The name field cannot be changed.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

400

Bad request. The request body is missing, malformed, or contains invalid values.

401

Unauthorized. The API key is missing or invalid.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/user-mgmt/end-user-groups/YOUR-GROUP-NAME \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X PUT -s -S -d \
'{
  "name": "mygroup",
  "cloudRoles": [
    "user"
  ],
  "restrictionFilters": [
    "cz0:Devices/HTTP"
  ]
}'

Response example (success)

 {}

Response example (failure)

 {
  "code": 3,
  "message": "invalid character '\"' after array element"
}

Delete a group

DELETE /v1/user-mgmt/end-user-groups/{group-name}

Delete a user group.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

401

Unauthorized. The API key is missing or invalid.

404

Not found. The specified resource does not exist.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/user-mgmt/end-user-groups/YOUR-GROUP-NAME \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X DELETE

Response example (success)

 {}

Response example (failure)

 {
  "code": 5,
  "message": "No group found by that name"
}
In this section: