{
  "id": "roles",
  "title": "Roles requests",
  "url": "https://redis.io/docs/latest/operate/rs/7.8/references/rest-api/requests/roles/",
  "summary": "Roles requests",
  "content": "\n| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-all-roles) | `/v1/roles` | Get all roles |\n| [GET](#get-role) | `/v1/roles/{uid}` | Get a single role |\n| [PUT](#put-role) | `/v1/roles/{uid}` | Update an existing role |\n| [POST](#post-role) | `/v1/roles` | Create a new role |\n| [DELETE](#delete-role) | `/v1/roles/{uid}` | Delete a role |\n\n## Get all roles {#get-all-roles}\n\n```sh\nGET /v1/roles\n```\n\nGet all roles' details.\n\n### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [view_all_roles_info]() | admin\u003cbr /\u003ecluster_member\u003cbr /\u003ecluster_viewer\u003cbr /\u003edb_member\u003cbr /\u003edb_viewer\u003cbr /\u003euser_manager |\n\n### Request {#get-all-request}\n\n#### Example HTTP request\n\n```sh\nGET /v1/roles\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n### Response {#get-all-response}\n\nReturns a JSON array of [role objects]().\n\n#### Example JSON body\n\n```json\n[\n    {\n        \"uid\": 1,\n        \"name\": \"Admin\",\n        \"management\": \"admin\"\n    },\n    {\n        \"uid\": 2,\n        \"name\": \"Cluster Member\",\n        \"management\": \"cluster_member\"\n    },\n    {\n        \"uid\": 3,\n        \"name\": \"Cluster Viewer\",\n        \"management\": \"cluster_viewer\"\n    },\n    {\n        \"uid\": 4,\n        \"name\": \"DB Member\",\n        \"management\": \"db_member\"\n    },\n    {\n        \"uid\": 5,\n        \"name\": \"DB Viewer\",\n        \"management\": \"db_viewer\"\n    },\n    {\n        \"uid\": 6,\n        \"name\": \"None\",\n        \"management\": \"none\"\n    },\n    {\n        \"uid\": 17,\n        \"name\": \"DBA\",\n        \"management\": \"admin\"\n    }\n]\n```\n\n#### Status codes {#get-all-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |\n| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support roles yet. |\n\n## Get role\n\n```sh\nGET /v1/roles/{int: uid}\n```\n\nGet the details of a single role.\n\n### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [view_role_info]() | admin\u003cbr /\u003ecluster_member\u003cbr /\u003ecluster_viewer\u003cbr /\u003edb_member\u003cbr /\u003edb_viewer\u003cbr /\u003euser_manager |\n\n### Request {#get-request}\n\n#### Example HTTP request\n\n```sh\nGET /v1/roles/1\n```\n\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The role's unique ID. |\n\n### Response {#get-response}\n\nReturns a [role object]().\n\n#### Example JSON body\n\n```json\n{\n     \"uid\": 17,\n     \"name\": \"DBA\",\n     \"management\": \"admin\"\n}\n```\n\n#### Status codes {#get-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success. |\n| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Operation is forbidden. |\n| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Role does not exist. |\n| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support roles yet. |\n\n## Update role {#put-role}\n\n```sh\nPUT /v1/roles/{int: uid}\n```\n\nUpdate an existing role's details.\n\n### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [update_role]() | admin\u003cbr /\u003euser_manager |\n\n### Request {#put-request}\n\n#### Example HTTP request\n\n```sh\nPUT /v1/roles/17\n```\n\n#### Example JSON body\n\n```json\n{\n     \"management\": \"cluster_member\"\n}\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### Query parameters\n\n| Field   | Type | Description |\n|---------|------|---------------|\n| dry_run |  | Validate the updated [role object]() but don't apply the update. |\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The role's unique ID. |\n\n#### Body\n\nInclude a [role object]() with updated fields in the request body.\n\n### Response {#put-response}\n\nReturns a [role object]() with the updated fields.\n\n#### Example JSON body\n\n```json\n{\n     \"uid\": 17,\n     \"name\": \"DBA\",\n     \"management\": \"cluster_member\"\n}\n```\n\n### Error codes {#put-error-codes}\n\nPossible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| unsupported_resource | The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version.|\n| name_already_exists | An object of the same type and name exists.|\n| change_last_admin_role_not_allowed | At least one user with admin role should exist.|\n\n#### Status codes {#put-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, role is created. |\n| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |\n| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to change a non-existant role. |\n| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support roles yet. |\n\n## Create role {#post-role}\n\n```sh\nPOST /v1/roles\n```\n\nCreate a new role.\n\n### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [create_role]() | admin\u003cbr /\u003euser_manager |\n\n### Request {#post-request}\n\n#### Example HTTP request\n\n```sh\nPOST /v1/roles\n```\n\n#### Example JSON body\n\n```json\n{\n     \"name\": \"DBA\",\n     \"management\": \"admin\"\n}\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### Query parameters\n\n| Field   | Type | Description |\n|---------|------|---------------|\n| dry_run |  | Validate the new [role object]() but don't apply the update. |\n\n#### Body\n\nInclude a [role object]() in the request body.\n\n### Response {#post-response}\n\nReturns the newly created [role object]().\n\n#### Example JSON body\n\n```json\n{\n     \"uid\": 17,\n     \"name\": \"DBA\",\n     \"management\": \"admin\"\n}\n```\n\n### Error codes {#post-error-codes}\n\nPossible `error_code`values:\n\n| Code | Description |\n|------|-------------|\n| unsupported_resource | The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version. |\n| name_already_exists | An object of the same type and name exists |\n| missing_field | A needed field is missing |\n\n#### Status codes {#post-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, role is created. |\n| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |\n| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support roles yet. |\n\n### Examples\n\n#### cURL\n\n```sh\ncurl -k -u \"[username]:[password]\" -X POST \\\n     -H 'Content-Type: application/json' \\\n     -d '{ \"name\": \"DBA\", \"management\": \"admin\" }' \\\n     https://[host][:port]/v1/roles\n```\n\n#### Python\n\n```python\nimport requests\nimport json\n\nurl = \"https://[host][:port]/v1/roles\"\n\nheaders = {\n  'Content-Type': 'application/json'\n}\n\npayload = json.dumps({\n    \"name\": \"DBA\",\n    \"management\": \"admin\"\n})\nauth=(\"[username]\", \"[password]\")\n\nresponse = requests.request(\"POST\", url,\n           auth=auth, headers=headers, payload=payload, verify=False)\n\nprint(response.text)\n```\n\n## Delete role {#delete-role}\n\n```sh\nDELETE /v1/roles/{int: uid}\n```\n\nDelete a role object.\n\n### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [delete_role]() | admin\u003cbr /\u003euser_manager |\n\n### Request {#delete-request}\n\n#### Example HTTP request\n\n```sh\nDELETE /v1/roles/1\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The role unique ID. |\n\n### Response {#delete-response}\n\nReturns a status code to indicate role deletion success or failure.\n\n#### Status codes {#delete-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, the role is deleted. |\n| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Role does not exist. |\n| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The request is not acceptable. |\n| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support roles yet. |\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-04-01T08:10:08-05:00",
  "children": []
}