/roles"
```
### Response
Returns the updated [User object](#user-object-fields) with the new roles.
This endpoint replaces all existing roles. Include every role the user should have, not just the ones you want to add. Invalid role names are silently ignored.
***
## Roles Reference
### Workspace Roles
Workspace roles control what a user can do within Visual Layer. Assign these via the `workspace_role` field when creating users, or through the [Workspace Members API](/api-reference/workspaces).
| Role | Permissions |
| ---------- | ------------------------------------------------------------------------------------------ |
| **Admin** | Full control — manage users, change roles, create and delete datasets, configure settings. |
| **Editor** | Create and edit datasets, run enrichment, export data. Cannot manage users or settings. |
| **Viewer** | Read-only access — explore datasets, run searches, view results. Cannot modify data. |
### Keycloak Realm Roles
These roles control access to the User Management API itself. They are managed through Keycloak and determine which API endpoints a user can call.
| Role | Grants Access To |
| -------------- | ------------------------------------------------------------ |
| `manage-users` | Create, update, delete users. Reset passwords. Manage roles. |
| `view-users` | List users, get user details, view sessions. |
| `query-users` | Query users (required for full user management). |
| `query-groups` | Query user groups (required for full user management). |
***
## Python Example
```python theme={"theme":"monokai"}
import requests
VL_BASE_URL = "https://"
session = requests.Session()
# Authenticate via OIDC flow first, then use the session cookie
# List all users
resp = session.get(f"{VL_BASE_URL}/api/v1/keycloak/admin/users")
resp.raise_for_status()
users = resp.json()
print(f"Total users: {users['total']}")
for user in users["users"]:
status = "active" if user["enabled"] else "disabled"
print(f" {user['username']} ({status}) — roles: {', '.join(user['roles'])}")
# Create a new editor
resp = session.post(
f"{VL_BASE_URL}/api/v1/keycloak/admin/users",
json={
"username": "new.analyst",
"password": "initialP@ss789",
"firstName": "New",
"lastName": "Analyst",
"workspace_role": "editor",
},
)
resp.raise_for_status()
new_user = resp.json()
print(f"\nCreated user: {new_user['username']} (ID: {new_user['id']})")
# Disable a user account
resp = session.patch(
f"{VL_BASE_URL}/api/v1/keycloak/admin/users/{new_user['id']}",
json={"enabled": False},
)
resp.raise_for_status()
print(f"Disabled user: {resp.json()['username']}")
```
***
## Response Codes
See [Error Handling](/api-reference/errors) for the error response format.
| HTTP Code | Meaning |
| --------- | ------------------------------------------------------------------------ |
| **200** | Request successful. |
| **201** | User created successfully. |
| **400** | Validation error, self-deletion attempt, or last admin deletion attempt. |
| **401** | Unauthorized — no valid session or token. |
| **403** | Forbidden — user management not enabled, or insufficient Keycloak roles. |
| **404** | User not found. |
| **500** | Internal Server Error — contact support if this persists. |
***
## Related Resources
Configure your Identity Provider for Single Sign-On with Visual Layer.
Manage workspace membership and roles programmatically.
View and update runtime configuration on self-hosted deployments.
Install and configure a self-hosted Visual Layer deployment.