Index

Get all users {#get-all-users}

GET /v1/users

Get a list of all users.

Permissions

Request {#get-all-request}

Example HTTP request

GET /v1/users

Headers

Response {#get-all-response}

Returns a JSON array of [user objects]({{< relref "/operate/rs/references/rest-api/objects/user" >}}).

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",
        "status": "active"
    },
    {
        "uid": 2,
        "password_issue_date": "2017-03-02T09:43:34Z",
        "email": "[email protected]",
        "name": "Jane Poe",
        "email_alerts": true,
        "role": "db_viewer",
        "auth_method": "regular",
        "status": "active"
    }
]

Status codes {#get-all-status-codes}

Get user {#get-user}

GET /v1/users/{int: uid}

Get a single user's details.

Permissions

Request {#get-request}

Example HTTP request

GET /v1/users/1

Headers

URL parameters

Response {#get-response}

Returns a [user object]({{< relref "/operate/rs/references/rest-api/objects/user" >}}) 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": "active"
}

Status codes {#get-status-codes}

Update user {#put-user}

PUT /v1/users/{int: uid}

Update an existing user's configuration.

Permissions

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

Request {#put-request}

Example HTTP request

PUT /v1/users/1

Example JSON body

{
     "email_alerts": false,
     "role_uids": [ 2, 4 ]
}

Headers

Query parameters

URL parameters

Request body

Include a [user object]({{< relref "/operate/rs/references/rest-api/objects/user" >}}) with updated fields in the request body.

Response {#put-response}

Returns the updated [user object]({{< relref "/operate/rs/references/rest-api/objects/user" >}}).

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",
     "role_uids": [ 2, 4 ],
     "auth_method": "regular"
}

{{<note>}} For [RBAC-enabled clusters]({{< relref "/operate/rs/security/access-control" >}}), the returned user details include role_uids instead of role. {{</note>}}

Error codes {#put-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:

Status codes {#put-status-codes}

Create user {#post-user}

POST /v1/users

Create a new user.

Permissions

Request {#post-request}

Example HTTP request

POST /v1/users

Headers

Query parameters

Body

Include a single [user object]({{< relref "/operate/rs/references/rest-api/objects/user" >}}) in the request body. The user object must have an email, password, and role.

{{<note>}} For [RBAC-enabled clusters]({{< relref "/operate/rs/security/access-control" >}}), use role_uids instead of role in the request body. {{</note>}}

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 {#post-response}

Returns the newly created [user object]({{< relref "/operate/rs/references/rest-api/objects/user" >}}).

Example JSON body

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

Error codes {#post-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:

Status codes {#post-status-codes}

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-user}

DELETE /v1/users/{int: uid}

Delete a user.

Permissions

Request {#delete-request}

Example HTTP request

DELETE /v1/users/1

Headers

URL parameters

Response {#delete-response}

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

Status codes {#delete-status-codes}