Reten Docs

Update User Roles

Update the role assignments for a user.

PUT /api/user/:id/roles

Replace the roles of a user of the active tenant: the user ends up with exactly the roles sent. The calling user must have a higher role than the target user, and can only assign roles below their own.

Auth: Required — user:update permission

Headers

HeaderRequiredValue
AuthorizationYesBearer <access_token>
x-tenant-idYesTenant UUID

Path Parameters

ParameterTypeDescription
idUUIDUser ID to update

Request Body

FieldTypeRequiredDescription
rolesstring[]YesRole values that replace the user's current roles, at least one: admin, fde, supervisor, operator, viewer (see Roles & Permissions)

Example

curl -X PUT https://api.reten.ai/api/user/550e8400-e29b-41d4-a716-446655440000/roles \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["supervisor"]
  }'
const userId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(`https://api.reten.ai/api/user/${userId}/roles`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ roles: ["supervisor"] }),
});
const data = await response.json();
import requests

user_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.put(
    f"https://api.reten.ai/api/user/{user_id}/roles",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
    json={"roles": ["supervisor"]},
)
data = response.json()

Response 200 OK

{
  "message": "User roles updated successfully"
}

Error Responses

StatusDescription
400Validation error — roles is empty (At least one role is required) or holds a value that is not a role
403Missing permission — Required permissions: user:update
403The target is the current user — Cannot modify your own roles
403The target user does not belong to the active tenant — Cannot modify roles for user outside your active tenant
403The target user's role is equal to or higher than the current user's — Cannot modify roles for user with equal or higher role
403A requested role is equal to or higher than the current user's — Cannot assign role <role> - you can only assign roles lower than your own
404User not found