Redis Documentation > Redis Enterprise Software > Reference > REST API > Requests > users

Users requests

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": "regular"
    }
]

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.

Edit on GitHub

Updated: August 17, 2023

Download PDF

Top