Skip to content

User account resources

The user management service employs the native identity management feature of Zenoss Cloud to create and manage user accounts.

Resource list

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

Creates one user account.

Request template

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

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

Request fields

user (object, required)
An object containing one user account specification.
email (string, required)
An email address. The address must be unique to your Zenoss Cloud environment.
password (string, required)

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)
firstName (string, optional)
A first name.
lastName (string, optional)
A last name.
groups (array, optional)

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 Zenoss Cloud. To add a group to an existing account, use the update account resource.

Response fields

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

  • 200 (success)
  • 400 (bad request)
  • 401 (unauthorized; missing or invalid authentication key)

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"
    ]
  }
}'

{ 
    "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 /v1/user-mgmt/end-user-accounts/{user-ID}

Get an account. The password field is not returned.

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

Status codes

  • 200 (success)
  • 401 (unauthorized; missing or invalid authentication key)
  • 404 (not found)

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

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

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

  • 200 (success)
  • 400 (bad request)
  • 401 (unauthorized; missing or invalid authentication key)

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"
    ]
  }
}'

{
    "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",
    }
}

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

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

  • 200 (success)
  • 401 (unauthorized; missing or invalid authentication key)
  • 404 (not found)

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

{}

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

An abstract preview of a JSON request to query user accounts.

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

Request fields

email (string, optional)
An email address.
firstName (string, optional)
A first name.
lastName (string, optional)
A last name.

Status codes

  • 200 (success)
  • 400 (bad request)
  • 401 (unauthorized; missing or invalid authentication key)

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"
}'

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

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