feat: Add simplified admin API for circle/team management

[Sam428-png]

Summary

• Adds /manage/ API endpoints that allow Nextcloud admins to fully manage circles (teams) without needing to be a member of the circle
• Unlike the existing /admin/{emulated}/ endpoints which require user emulation per request, these endpoints use super sessions to operate directly as admin
• Based on the SURF circlesadmin app which has been running in production

New endpoints

Method	Endpoint	Description
GET	/manage/circles	List all circles
GET	/manage/circles/{circleId}	Get circle details with members
POST	/manage/circles	Create circle (params: name, owner, desc, federated)
PUT	/manage/circles/{circleId}	Update circle name/description
DELETE	/manage/circles/{circleId}	Delete circle
GET	/manage/circles/{circleId}/members	List members
POST	/manage/circles/{circleId}/members	Add member
DELETE	/manage/circles/{circleId}/members/{memberId}	Remove member
PUT	/manage/circles/{circleId}/members/{memberId}/level	Set member level

Files added/changed

• New: lib/Service/CirclesAdminService.php — business logic using CirclesManager super/occ sessions
• New: lib/Controller/CircleApiController.php — circle CRUD endpoints (@AdminRequired)
• New: lib/Controller/MemberApiController.php — member management endpoints (@AdminRequired)
• Modified: appinfo/routes.php — 9 new OCS routes under /manage/

Test plan

• GET /manage/circles — returns list of all circles
• POST /manage/circles — create local circle with description
• POST /manage/circles with federated=1 — create federated circle (config=0)
• GET /manage/circles/{id} — returns circle detail with members array
• PUT /manage/circles/{id} — update name and description
• DELETE /manage/circles/{id} — delete circle
• POST /manage/circles/{id}/members — add member to circle
• GET /manage/circles/{id}/members — list all members
• PUT /manage/circles/{id}/members/{id}/level — change member level
• DELETE /manage/circles/{id}/members/{id} — remove member

All endpoints tested on Nextcloud 32 and Nextcloud 33 instances.

[cristianscheid]

@Sam428-png thanks a lot for taking the time to implement this PR, really appreciated! I tested it locally and left a couple of suggestions inline. I also have one more to add: looking at how other controllers are named and structured, I think it would make sense to merge CircleApiController and MemberApiController into a single file called AdminApiController, and rename CirclesAdminService to AdminApiService for consistency. Thanks again!

[Sam428-png]

Thanks, all feedback addressed!

[Sam428-png]

Hi @cristianscheid, thanks again for the thorough review! While implementing your suggestion for createCircle, I noticed a potential issue: looking at CircleService::createCircle(), it sets CFG_PERSONAL = 2 by default — not 0 as observed in your tests. This means that when $federated = false, the config returned in the response (0) may not match what is actually stored in the database (2). Would it make more sense to re-fetch the circle after the update (like updateCircle() does) to return the actual persisted config value? Happy to adjust if you agree!

[cristianscheid]

Hi @cristianscheid, thanks again for the thorough review! While implementing your suggestion for createCircle, I noticed a potential issue: looking at CircleService::createCircle(), it sets CFG_PERSONAL = 2 by default — not 0 as observed in your tests. This means that when $federated = false, the config returned in the response (0) may not match what is actually stored in the database (2). Would it make more sense to re-fetch the circle after the update (like updateCircle() does) to return the actual persisted config value? Happy to adjust if you agree!

Hey @Sam428-png, thank you for taking the time for this PR! Given the situation you just described, maybe we could do something like this then?

// instead of
if ($federated) {
	$updates['config'] = $federatedConfigValue;
}
// something like
$updates['config'] = $federated ? $federatedConfigValue : 0;

Does that make sense to you?

[github-actions]

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

[Sam428-png]

Thanks for the feedback, and apologies for the late reply! This is now fixed in 9ff06b3 — config is always set explicitly (either CFG_ROOT + CFG_FEDERATED or 0), so the stored value matches the response payload.

[cristianscheid]

@Sam428-png thanks for the adjustments! One more thing I caught after re-review: since $updates will now always be non-empty, there's no longer need for the if (!empty($updates)) check anymore.

[Sam428-png]

Thanks! Applied the suggestion in ea44975 — the empty-updates guard is gone and $updates is initialized with config directly.

[cristianscheid]

Thanks @Sam428-png! Could you please squash your commits into one and sign off? Only the first commit has a sign-off.

[Sam428-png]

Done! Squashed into a single commit with sign-off.

[Sam428-png]

Hi @cristianscheid, thanks for the thorough reviews! All feedback from the latest round has been applied in 31c36df:

• Renamed AdminApiController → AdminManageController (class + file)
• Renamed AdminApiService → AdminManageService (class + file)
• Route prefix changed to /admin/manage/ with AdminManage# handlers
• Property renamed to $adminManageService for consistency

Squashed into a single signed-off commit. Ready for another look!

[cristianscheid]

Adds /manage/ API endpoints that allow Nextcloud admins to fully manage circles (teams) without needing to be a member of the circle

After internal discussion and looking at our codebase again, more specifically at our existing admin routes, I see that it's already possible to manage circles without being a member of them. If you make requests as admin and specify the circle's owner user id, you can manage the circle.

Functionality wise, I think the only new feature that this PR would include is the ability to list all circles in a single endpoint without having to specify a user. Currently our ocs/v2.php/apps/circles/admin/<user_id>/circles route returns circles only for a given user. Other than that, I was able to achieve the same functionality using the endpoints below, which makes me question if it would really be necessary to add another controller/endpoints, since we already have something that works.

## already existing routes in circles/appinfo/routes.php

# get circles that user is part of
curl -X GET \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<user_id>/circles"

# get circle details
curl -X GET \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>"

# create new circle
curl -X POST \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -d '{"name":"<circle_name>"}' \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles"

# set circle name
curl -X PUT \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -d '{"value":"<circle_name>"}' \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>/name"

# set circle description
curl -X PUT \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -d '{"value":"<description>"}' \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>/description"

# set circle config (e.g. enable federation: Circle::CFG_ROOT + Circle::CFG_FEDERATED = 40960)
curl -X PUT \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -d '{"value":40960}' \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>/config"

# remove circle
curl -X DELETE \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>"

# get circle members
curl -X GET \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>/members"

# add member
curl -X POST \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -d '{"userId":"<user_id>","type":<member_type>}' \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>/members"

# remove member
curl -X DELETE \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>/members/<member_id>"

# set member level
curl -X PUT \
  -u "admin:admin" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/json" \
  -d '{"level":<member_level>}' \
  "http://nextcloud.local/ocs/v2.php/apps/circles/admin/<owner_user_id>/circles/<circle_id>/members/<member_id>/level"