PHPeerTube - A PHP‑based federated video platform, inspired by PeerTube.

Copyright (C) 2025 Lucentinian Works Co Ltd

Change User Role (Administrator)

This document provides an example of how an administrator can change the role of an existing user using a PUT request with curl.

Endpoint

PUT /admin/users/{user_id}/role

Request Body

The request body should be a JSON object containing the new role for the user.

{
  "role": "new_role_name"
}

Example

To change the role of a user with user_id 123 to moderator, you would use the following curl command:

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ADMIN_AUTH_TOKEN>" \
  -d '{"role": "moderator"}' \
  http://phpeertube.ehehdada.com/admin/users/123/role

Parameters

• <ADMIN_AUTH_TOKEN>: Replace this with a valid authentication token for an administrator user.
• user_id: The ID of the user whose role you want to change.
• new_role_name: The desired new role for the user. Valid values are user, moderator, or admin.

Success Response

If the request is successful, you will receive a 200 OK response with the updated user object.

{
  "id": 123,
  "username": "johndoe",
  "email": "johndoe@example.com",
  "role": "moderator",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:30:00Z"
}

Error Responses

401 Unauthorized

If the authentication token is missing or invalid.

{
  "error": "Unauthorized",
  "message": "Authentication required."
}

403 Forbidden

If the authenticated user does not have administrator privileges.

{
  "error": "Forbidden",
  "message": "Insufficient permissions."
}

404 Not Found

If the specified user_id does not exist.

{
  "error": "Not Found",
  "message": "User not found."
}

400 Bad Request

If the role in the request body is invalid or missing.

{
  "error": "Bad Request",
  "message": "Invalid role specified."
}