# Confluence Users & Groups — Agent Guidance

Covers `src/tools/users-groups.ts` (23 tools) and `admin-users-groups.ts` (10) — user/group
lookup, membership, watching, and admin-level account/group management. Confirmed live 2026-08-20;
see `docs/plans/2026-08-20-full-api-coverage.md` batches 9 and 10 for the full record.

## Read-tier vs. admin-tier split

`get_user`, `get_current_user`, `list_users`, `get_user_groups`, `get_anonymous_user_info`,
`update_current_user`, `change_current_user_password`, `update_user_settings`, and all the content/
space watch tools work with `CONFLUENCE_USER_TOKEN` alone. Everything group-related
(`admin_list_groups`, `admin_get_group*`, `admin_add/remove_user_to_group`) plus all of
`admin-users-groups.ts` (create/delete/update/disable/enable user, create group, change another
user's password, list active users) requires `CONFLUENCE_ADMIN_TOKEN` and won't even appear in
`ListTools` without it.

## `admin_list_active_users` lags behind real account state

Confirmed live: a freshly created, enabled user with a real password did **not** appear in
`admin_list_active_users`, even immediately after `admin_enable_user`. The user genuinely existed
(confirmed via `get_user`) and the tool's own request/response handling is correct — "active" here
evidently means something more specific than "exists and isn't disabled," most likely "has logged
in at least once" (unconfirmed; this debug environment can't easily drive a real browser login as
a test user). Don't treat an empty or missing entry here as proof an account doesn't exist — check
with `get_user` instead.

## Deleting a user leaves their personal space behind

Same finding as `skill://spaces-admin`: `admin_delete_user` does not delete the user's personal
space. It survives at `~<username>`, fully accessible, until someone calls `delete_space` on it
separately.

## Space-scoped group-membership testing pattern

`admin_add_user_to_group`/`admin_remove_user_from_group`/`admin_get_group_members` were
live-verified against a real *throwaway* group created via the raw `POST /rest/api/admin/group`
endpoint (now wrapped as `admin_create_group`), never against the real `confluence-users`/
`confluence-administrators` groups an active session depends on. If you need to test group
membership changes yourself, do the same — create a disposable group first, don't experiment on
the groups your own session's permissions come from.

## `change_current_user_password` is real but untested here, on purpose

Implemented and unit-tested against the documented schema, but never actually called against the
live debug instance — there's no GET endpoint to read a password back, and the real current
password on a shared debug instance isn't reliably known (the setup-wizard default may have
changed). If you need to verify this tool works, do it against a disposable test account you
created yourself, not the shared `admin` account.

## `POST /admin/group` needs an explicit `type` field

Not exposed as a gotcha to callers of `admin_create_group` (the tool handles it), but worth knowing
if you're ever constructing a raw request: Confluence's `Group` schema has no documented properties
at all, but the real endpoint requires `{"type": "group", "name": "..."}` — omitting `type` fails
with `"Could not resolve subtype of ... Group: missing type id property 'type'"`.