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.

Required permissions

Permission name
view_all_users_info

Request

Example HTTP request

GET /users

Request 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.

Required permissions

Permission name
view_user_info

Request

Example HTTP request

GET /users/1

Request 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.

Required permissions

Permission name
update_user (Although any user can change their own name, password, or alerts)

Request

Example HTTP request

PUT /users/1

Example JSON body

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

Request 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.

Required permissions

Permission name
create_new_user

Request

Example HTTP request

POST /users

Example JSON body

{
     "email": "[email protected]",
     "password": "my-password",
     "name": "John Doe",
     "email_alerts": true,
     "bdbs_email_alerts": ["1","2"],
     "role": "db_viewer",
     "auth_method": "regular"
}

Request headers

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

Request body

Include a single user object, with an email and a password, in the request body.

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

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.

Delete user

DELETE /v1/users/{int: uid}

Delete a user.

Required permissions

Permission name
delete_user

Request

Example HTTP request

DELETE /users/1

Request 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.