Method Path Description
GET /v1/users Get all users
GET /v1/users/{uid} Get a single user
PUT /v1/users/{uid} Update a user’s configuration
POST /v1/users Create a new user
DELETE /v1/users/{uid} Delete a user

Get all users

GET /v1/users

Get a list of all users.

Permissions

Permission name Roles
view_all_users_info admin

Request

Example HTTP request

GET /users

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

Response

Returns a JSON array of user objects.

Example JSON body

[
    {
        "uid": 1,
        "password_issue_date": "2017-03-02T09:43:34Z",
        "email": "[email protected]",
        "name": "John Doe",
        "email_alerts": true,
        "bdbs_email_alerts": ["1","2"],
        "role": "admin",
        "auth_method": "regular"
    },
    {
        "uid": 2,
        "password_issue_date": "2017-03-02T09:43:34Z",
        "email": "[email protected]",
        "name": "Jane Poe",
        "email_alerts": true,
        "role": "db_viewer",
        "auth_method": "external"
    }
]

Status codes

Code Description
200 OK No error

Get user

GET /v1/users/{int: uid}

Get a single user’s details.

Permissions

Permission name Roles
view_user_info admin

Request

Example HTTP request

GET /users/1

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

URL parameters

Field Type Description
uid integer The user’s unique ID

Response

Returns a user object that contains the details for the specified user ID.

Example JSON body

{
    "uid": 1,
    "password_issue_date": "2017-03-07T15:11:08Z",
    "role": "db_viewer",
    "email_alerts": true,
    "bdbs_email_alerts": ["1","2"],
    "email": "[email protected]",
    "name": "John Doe",
    "auth_method": "regular"
}

Status codes

Code Description
200 OK Success.
403 Forbidden Operation is forbidden.
404 Not Found User does not exist.

Update user

PUT /v1/users/{int: uid}

Update an existing user’s configuration.

Permissions

Permission name Roles
update_user admin

Any user can change their own name, password, or alert preferences.

Request

Example HTTP request

PUT /users/1

Example JSON body

{
     "name": "Jane Poe",
     "email_alerts": false
}

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

URL parameters

Field Type Description
uid integer The user’s unique ID

Request body

Include a user object with updated fields in the request body.

Response

Returns the updated user object.

Example JSON body

{
     "uid": 1,
     "password_issue_date": "2017-03-07T15:11:08Z",
     "email": "[email protected]",
     "name": "Jane Poe",
     "email_alerts": false,
     "role": "db_viewer",
     "auth_method": "regular"
}
Note:
For RBAC-enabled clusters, the returned user details include role_uids instead of role.

Error codes

When errors are reported, the server may return a JSON object with error_code and message field that provide additional information. The following are possible error_code values:

Code Description
password_not_complex The given password is not complex enough (Only works when the password_complexity feature is enabled).
new_password_same_as_current The given new password is identical to the old password.
email_already_exists The given email is already taken.
change_last_admin_role_not_allowed At least one user with admin role should exist.

Status codes

Code Description
200 OK Success, the user is updated.
400 Bad Request Bad or missing configuration parameters.
404 Not Found Attempting to change a non-existing user.
406 Not Acceptable The requested configuration is invalid.

Create user

POST /v1/users

Create a new user.

Permissions

Permission name Roles
create_new_user admin

Request

Example HTTP request

POST /users

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

Body

Include a single user object in the request body. The user object must have an email, password, and role.

Note:
For RBAC-enabled clusters, use role_uids instead of role in the request body.

email_alerts can be configured either as:

  • true - user will receive alerts for all databases configured in bdbs_email_alerts. The user will receive alerts for all databases by default if bdbs_email_alerts is not configured. bdbs_email_alerts can be a list of database UIDs or [‘all’] meaning all databases.

  • false - user will not receive alerts for any databases

Example JSON body
{
     "email": "[email protected]",
     "password": "my-password",
     "name": "Pat Doe",
     "email_alerts": true,
     "bdbs_email_alerts": ["1","2"],
     "role_uids": [ 3, 4 ],
     "auth_method": "regular"
}

Response

Returns the newly created user object.

Example JSON body

{
     "uid": 1,
     "password_issue_date": "2017-03-07T15:11:08Z",
     "email": "[email protected]",
     "name": "Jane Poe",
     "email_alerts": true,
     "bdbs_email_alerts": ["1","2"],
     "role": "db_viewer",
     "auth_method": "regular"
}

Error codes

When errors are reported, the server may return a JSON object with error_code and message field that provide additional information.

The following are possible error_code values:

Code Description
password_not_complex The given password is not complex enough (Only works when the password_complexity feature is enabled).
email_already_exists The given email is already taken.
name_already_exists The given name is already taken.

Status codes

Code Description
200 OK Success, user is created.
400 Bad Request Bad or missing configuration parameters.
409 Conflict User with the same email already exists.

Examples

cURL

$ curl -k -X POST -u '[username]:[password]' \
       -H 'Content-Type: application/json' \
       -d '{ "email": "[email protected]", \
           "password": "my-password", \
           "name": "Pat Doe", \
           "email_alerts": true, \
           "bdbs_email_alerts": ["1","2"], \
           "role_uids": [ 3, 4 ], \
           "auth_method": "regular" }' \
       'https://[host][:port]/v1/users'

Python

import requests
import json

url = "https://[host][:port]/v1/users"
auth = ("[username]", "[password]")

payload = json.dumps({
  "email": "[email protected]",
  "password": "my-password",
  "name": "Pat Doe",
  "email_alerts": True,
  "bdbs_email_alerts": [
    "1",
    "2"
  ],
  "role_uids": [
    3,
    4
  ],
  "auth_method": "regular"
})

headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, auth=auth, headers=headers, data=payload, verify=False)

print(response.text)

Delete user

DELETE /v1/users/{int: uid}

Delete a user.

Permissions

Permission name Roles
delete_user admin

Request

Example HTTP request

DELETE /users/1

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

URL parameters

Field Type Description
uid integer The user’s unique ID

Response

Returns a status code to indicate the success or failure of the user deletion.

Status codes

Code Description
200 OK Success, the user is deleted.
406 Not Acceptable The request is not acceptable.