زیرکاربران

مرجع کامل endpointهای بخش «زیرکاربران» در API کلاینت پافرلند.

Endpoints زیرکاربران

مدیریت کاربرانی که به سرور شما دسترسی دارند. مجوزهای لازم: user.create، user.read، user.update و user.delete (مالک سرور از این محدودیت‌ها مستثنی است).

در مسیرهای زیر {user} شناسه‌ی UUID کاربر است. لیست مجوزهای مجاز از endpoint GET /api/client/permissions قابل دریافت است.

GET/api/client/servers/{server}/users

فهرست کاربرانی که به سرور دسترسی دارند را برمی‌گرداند. هر زیرکاربر شامل uuid، username، email، image (آواتار)، 2fa_enabled، created_at و permissions است.

curl "https://pufferland.ir/api/client/servers/1a85a183/users" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "list",
  "data": []
}

GET/api/client/servers/{server}/users/{user}

جزئیات یک زیرکاربر مشخص را برمی‌گرداند.

curl "https://pufferland.ir/api/client/servers/1a85a183/users/190d9c5d-8ac4-4d35-b3ba-d4e90e72af1f" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

POST/api/client/servers/{server}/users

کاربر جدیدی با مجوزهای مشخص به سرور دعوت می‌کند.

فیلد	نوع	الزام	توضیح
`email`	string	✓	ایمیل کاربر (باید حسابی با این ایمیل وجود داشته باشد).
`permissions`	array	✓	آرایه‌ای از کلیدهای مجوز.

خطاها: 400 با کد TooManySubusersException، 409 با کد UserAlreadyHasAccessException، 422 با کد ValidationException و 404 با کد UserNotFoundException.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/users" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email": "friend@example.com", "permissions": ["control.start", "control.stop", "control.console"]}'

POST/api/client/servers/{server}/users/{user}

مجوزهای یک زیرکاربر را به‌روزرسانی می‌کند.

این درخواست، مجوزهای فعلی را کاملاً جایگزین می‌کند — همیشه مجموعه‌ی کامل مجوزهای مورد نظر را ارسال کنید.

فیلد	نوع	الزام	توضیح
`permissions`	array	✓	آرایه‌ی کامل مجوزهای جدید.

پاسخ، زیرکاربر با مجوزهای به‌روزشده است.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/users/190d9c5d-8ac4-4d35-b3ba-d4e90e72af1f" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"permissions": ["control.start", "control.stop"]}'

DELETE/api/client/servers/{server}/users/{user}

دسترسی کاربر به سرور را بلافاصله لغو می‌کند و کاربر از سرور خارج می‌شود. پاسخ موفق: 204. خطای 400 با کد CannotRemoveServerOwnerException برای حذف مالک سرور.

curl -X DELETE "https://pufferland.ir/api/client/servers/1a85a183/users/190d9c5d-8ac4-4d35-b3ba-d4e90e72af1f" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

204 No Content