diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 86c29ab380..6b952ba396 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -62,7 +62,7 @@ URL parameters:
- `user_id`: fully-qualified user id: for example, `@user:server.com`.
-## Create or modify Account
+## Create or modify account
This API allows an administrator to create or modify a user account with a
specific `user_id`.
@@ -78,28 +78,29 @@ with a body of:
```json
{
"password": "user_password",
- "displayname": "User",
+ "logout_devices": false,
+ "displayname": "Alice Marigold",
+ "avatar_url": "mxc://example.com/abcde12345",
"threepids": [
{
"medium": "email",
- "address": "<user_mail_1>"
+ "address": "alice@example.com"
},
{
"medium": "email",
- "address": "<user_mail_2>"
+ "address": "alice@domain.org"
}
],
"external_ids": [
{
- "auth_provider": "<provider1>",
- "external_id": "<user_id_provider_1>"
+ "auth_provider": "example",
+ "external_id": "12345"
},
{
- "auth_provider": "<provider2>",
- "external_id": "<user_id_provider_2>"
+ "auth_provider": "example2",
+ "external_id": "abc54321"
}
],
- "avatar_url": "<avatar_url>",
"admin": false,
"deactivated": false,
"user_type": null
@@ -112,41 +113,51 @@ Returns HTTP status code:
URL parameters:
-- `user_id`: fully-qualified user id: for example, `@user:server.com`.
+- `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
+- `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
+- `logout_devices` - **bool**, optional, defaults to `true`. If set to `false`, devices aren't
logged out even when `password` is provided.
-- `displayname` - string, optional, defaults to the value of `user_id`.
-- `threepids` - array, optional, allows setting the third-party IDs (email, msisdn)
- - `medium` - string. Kind of third-party ID, either `email` or `msisdn`.
- - `address` - string. Value of third-party ID.
- belonging to a user.
-- `external_ids` - array, optional. Allow setting the identifier of the external identity
- provider for SSO (Single sign-on). Details 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. ID of the external identity provider. Value of `idp_id`
- in the homeserver configuration. Note that no error is raised if the provided
- value is not in the homeserver configuration.
- - `external_id` - string, user ID in the external identity provider.
-- `avatar_url` - string, optional, must be a
+- `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).
-- `admin` - bool, optional, defaults to `false`.
-- `deactivated` - bool, optional. If unspecified, deactivation state will be left
- unchanged on existing accounts and set to `false` for new accounts.
- A user cannot be erased by deactivating with this API. For details on
- deactivating users see [Deactivate Account](#deactivate-account).
-- `user_type` - string or null, optional. If provided, the user type will be
- adjusted. If `null` given, the user type will be cleared. Other
- allowed options are: `bot` and `support`.
-
-If the user already exists then optional parameters default to the current value.
-
-In order to re-activate an account `deactivated` must be set to `false`. If
-users do not login via single-sign-on, a new `password` must be provided.
+ 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. 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: the `password` field must also be set if both of the following are true:
+ - `deactivated` is set to `false` and the user was previously deactivated (you are reactivating this user)
+ - Users are allowed to set their password on this homeserver (both `password_config.enabled` and
+ `password_config.localdb_enabled` config options are set to `true`).
+ 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).
+- `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
|
