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
Request
Example HTTP request
GET /users
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
Request
Example HTTP request
GET /users/1
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
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
}
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"
}
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
Create user
POST /v1/users
Create a new user.
Required permissions
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"
}
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.
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
Delete user
DELETE /v1/users/{int: uid}
Delete a user.
Required permissions
Request
Example HTTP request
DELETE /users/1
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