| 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 a list of all users.
Permissions
Request
Example HTTP request
| 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": "user@redislabs.com",
"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": "user2@redislabs.com",
"name": "Jane Poe",
"email_alerts": true,
"role": "db_viewer",
"auth_method": "regular",
"status": "active"
}
]
Status codes
Get user
Get a single user’s details.
Permissions
Request
Example HTTP request
| 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": "user@redislabs.com",
"name": "John Doe",
"auth_method": "regular",
"status": "active"
}
Status codes
Update user
Update an existing user’s configuration.
Permissions
Any user can change their own name, password, or alert preferences.
Request
Example HTTP request
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": "user@redislabs.com",
"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
Create a new user.
Permissions
Request
Example HTTP request
| 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.
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": "newuser@redis.com",
"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": "user@redislabs.com",
"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
Examples
cURL
$ curl -k -X POST -u '[username]:[password]' \
-H 'Content-Type: application/json' \
-d '{ "email": "newuser@redis.com", \
"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": "newuser@redis.com",
"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
Request
Example HTTP request
| 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
