Skip to main content

User account resources

The user management service employs the native identity management feature of Virtana Service Observability to create and manage user accounts.

Resource list

Create a user account

POST /v1/user-mgmt/end-user-accounts

Creates one user account.

Request template

JSON request to create one user:

{
  "user": {
    "email": "<email>",
    "password": "<password>",
    "lastName": "<first>",
    "firstName": "<last>",
    "groups": [ "<group>" ]
  }
}

Request fields

Field

Type

Required

Description

user

Object

Yes

An object containing one user account specification.

user.email

String

Yes

An email address. The address must be unique to your Virtana Service Observability environment.

user.password

String

Yes

A password. Passwords must be a minimum of 8 characters, with no more than two identical characters in a row, and must include at least one character from three of the following classes:

  • Special characters (! @ # $ % ^ & *)

  • Lower-case letters (a-z)

  • Upper-case letters (A-Z)

  • Digits (0-9)

user.firstName

String

No

A first name.

user.lastName

String

No

A last name.

user.groups

Array

No

A list of one or more existing groups.

A user account must have at least one group before it can be used to log in to Virtana Service Observability. To add a group to an existing account, use the update account resource.

Response fields

Field

Description

createdAt

The date and time at which the user account was created.

createdBy

The user that created the user account (unknown for API requests).

id

The identifier of the user account.

updatedAt

The date and time at which the user account was updated.

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-accounts \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "user": {
    "email": "user_fake@example.com",
    "password": "YOUR-USER-PASSWORD",
    "lastName": "Doe",
    "firstName": "John",
    "groups": [
      "group1",
      "group2"
    ]
  }
}'

Response example

 {
  "user": {
    "createdAt": "2021-07-08T18:46:31.060Z",
    "createdBy": "unknown",
    "email": "user_fake@example.com",
    "firstName": "John",
    "groups": [
      "group1",
      "group2"
    ],
    "id": "YOUR-USER-ID",
    "lastName": "Doe",
    "updatedAt": "2021-07-08T18:46:31.060Z"
  }
}

Get an account

GET /v1/user-mgmt/end-user-accounts/{user-ID}

Get one account. The password field is not returned.

Use the get user IDs resource to get a specific user ID.

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-accounts/YOUR-USER-ID \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET

Response example

 {
  "user": {
    "id": "YOUR-USER-ID",
    "email": "user_fake@example.com",
    "lastName": "Doe",
    "firstName": "John",
    "groups": [
      "group1",
      "group2"
    ],
    "createdBy": "unknown",
    "createdAt": "2021-07-08T18:46:31.060Z",
    "updatedAt": "2021-07-08T18:46:31.060Z"
  }
}

Update an account

PUT /v1/user-mgmt/end-user-accounts/{user-ID}

Update an existing account.

Use the get user IDs resource to get a specific user ID.

Request fields

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

To prevent a user from logging in, specify an empty array for the groups field.

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-accounts/YOUR-USER-ID \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X PUT -s -S -d \
'{
  "user": {
    "groups": [
      "group3",
      "group4"
    ]
  }
}'

Response example (success)

 {
  "user": {
    "createdAt": "2021-07-08T18:46:31.060Z",
    "createdBy": "unknown",
    "email": "user_fake@example.com",
    "firstName": "John",
    "groups": [
      "group3",
      "group4"
    ],
    "id": "YOUR-USER-ID",
    "lastName": "Doe",
    "updatedAt": "2021-07-08T20:08:49.200Z"
  }
}

Response example (failure)

 {
  "code": 3,
  "message": "Group from the request doesn't exist"
}

Delete an account

DELETE /v1/user-mgmt/end-user-accounts/{user-ID}

Delete a user account.

Use the get user IDs resource to get a specific user ID.

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-accounts/YOUR-USER-ID \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X DELETE

Response example

 {}

Get user IDs

POST /v1/user-mgmt/end-user-account-ids

Get an array of user IDs of accounts that match the search criteria.

Only full matches are returned (no partial matches).

Request template

JSON request to query user accounts:

{
  "user": {
    "email": "<email>",
    "lastName": "<first>",
    "firstName": "<last>"
  }
}

Request fields

Field

Type

Required

Description

email

String

No

An email address.

firstName

String

No

A first name.

lastName

String

No

A last name.

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-account-ids \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "email": "user_fake@example.com",
  "lastName": "Doe",
  "firstName": "John"
}'

Response example (success)

 {
  "ids": [
    "YOUR-USER-ID"
  ]
}

Response example (failure)

 {
  "code": 3,
  "message": "invalid input, empty request or some fields"
}
In this section: