user_admin_api.md

# User Admin API

To use it, you will need to authenticate by providing an `access_token`
for a server admin: see [Admin API](../usage/administration/admin_api/).

## Query User Account

This API returns information about a specific user account.

The api is:

```
GET /_synapse/admin/v2/users/<user_id>
```

It returns a JSON body like the following:

```jsonc
{
    "name": "@user:example.com",
    "displayname": "User", // can be null if not set
    "threepids": [
        {
            "medium": "email",
            "address": "<user_mail_1>",
            "added_at": 1586458409743,
            "validated_at": 1586458409743
        },
        {
            "medium": "email",
            "address": "<user_mail_2>",
            "added_at": 1586458409743,
            "validated_at": 1586458409743
        }
    ],
    "avatar_url": "<avatar_url>",  // can be null if not set
    "is_guest": 0,
    "admin": 0,
    "deactivated": 0,
    "erased": false,
    "shadow_banned": 0,
    "creation_ts": 1560432506,
    "last_seen_ts": 1732919539393,
    "appservice_id": null,
    "consent_server_notice_sent": null,
    "consent_version": null,
    "consent_ts": null,
    "external_ids": [
        {
            "auth_provider": "<provider1>",
            "external_id": "<user_id_provider_1>"
        },
        {
            "auth_provider": "<provider2>",
            "external_id": "<user_id_provider_2>"
        }
    ],
    "user_type": null,
    "locked": false,
    "suspended": false
}
```

URL parameters:

- `user_id`: fully-qualified user id: for example, `@user:server.com`.

## Create or modify account

This API allows an administrator to create or modify a user account with a
specific `user_id`.

This api is:

```
PUT /_synapse/admin/v2/users/<user_id>
```

with a body of:

```json
{
    "password": "user_password",
    "logout_devices": false,
    "displayname": "Alice Marigold",
    "avatar_url": "mxc://example.com/abcde12345",
    "threepids": [
        {
            "medium": "email",
            "address": "alice@example.com"
        },
        {
            "medium": "email",
            "address": "alice@domain.org"
        }
    ],
    "external_ids": [
        {
            "auth_provider": "example",
            "external_id": "12345"
        },
        {
            "auth_provider": "example2",
            "external_id": "abc54321"
        }
    ],
    "admin": false,
    "deactivated": false,
    "user_type": null,
    "locked": false
}
```

Returns HTTP status code:
- `201` - When a new user object was created.
- `200` - When a user was modified.

URL parameters:

- `user_id` - A fully-qualified user id. For example, `@user:server.com`.

Body parameters:

- `password` - **string**, optional. If provided, the user's password is updated and all
  devices are logged out, unless `logout_devices` is set to `false`.
- `logout_devices` - **bool**, optional, defaults to `true`. If set to `false`, devices aren't
  logged out even when `password` is provided.
- `displayname` - **string**, optional. If set to an empty string (`""`), the user's display name
  will be removed.
- `avatar_url` - **string**, optional. Must be a
  [MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris).
  If set to an empty string (`""`), the user's avatar is removed.
- `threepids` - **array**, optional. If provided, the user's third-party IDs (email, msisdn) are
  entirely replaced with the given list. Each item in the array is an object with the following
  fields:
  - `medium` - **string**, required. The type of third-party ID, either `email` or `msisdn` (phone number).
  - `address` - **string**, required. The third-party ID itself, e.g. `alice@example.com` for `email` or
    `447470274584` (for a phone number with country code "44") and `19254857364` (for a phone number
    with country code "1") for `msisdn`.
  Note: If a threepid is removed from a user via this option, Synapse will also attempt to remove
  that threepid from any identity servers it is aware has a binding for it.
- `external_ids` - **array**, optional. Allow setting the identifier of the external identity
  provider for SSO (Single sign-on). More details are in the configuration manual under the
  sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
  - `auth_provider` - **string**, required. The unique, internal ID of the external identity provider.
    The same as `idp_id` from the homeserver configuration. If using OIDC, this value should be prefixed
    with `oidc-`. Note that no error is raised if the provided value is not in the homeserver configuration.
  - `external_id` - **string**, required. An identifier for the user in the external identity provider.
    When the user logs in to the identity provider, this must be the unique ID that they map to.
- `admin` - **bool**, optional, defaults to `false`. Whether the user is a homeserver administrator,
  granting them access to the Admin API, among other things.
- `deactivated` - **bool**, optional. If unspecified, deactivation state will be left unchanged.

  Note:
  - For the password field there is no strict check of the necessity for its presence.
    It is possible to have active users without a password, e.g. when authenticating with OIDC is configured.
    You must check yourself whether a password is required when reactivating a user or not.
  - It is not possible to set a password if the config option `password_config.localdb_enabled` is set `false`.
  Users' passwords are wiped upon account deactivation, hence the need to set a new one here.

  Note: a user cannot be erased with this API. For more details on
  deactivating and erasing users see [Deactivate Account](#deactivate-account).
- `locked` - **bool**, optional. If unspecified, locked state will be left unchanged.
- `user_type` - **string** or null, optional. If not provided, the user type will be
  not be changed. If `null` is given, the user type will be cleared.
  Other allowed options are: `bot` and `support`.

## List Accounts
### List Accounts (V2)

This API returns all local user accounts.
By default, the response is ordered by ascending user ID.

```
GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
```

A response body like the following is returned:

```json
{
    "users": [
        {
            "name": "<user_id1>",
            "is_guest": 0,
            "admin": 0,
            "user_type": null,
            "deactivated": 0,
            "erased": false,
            "shadow_banned": 0,
            "displayname": "<User One>",
            "avatar_url": null,
            "creation_ts": 1560432668000,
            "locked": false
        }, {
            "name": "<user_id2>",
            "is_guest": 0,
            "admin": 1,
            "user_type": null,
            "deactivated": 0,