1# User Admin API 2 3## Query User Account 4 5This API returns information about a specific user account. 6 7The api is: 8 9``` 10GET /_synapse/admin/v2/users/<user_id> 11``` 12 13To use it, you will need to authenticate by providing an `access_token` for a 14server admin: [Admin API](../usage/administration/admin_api) 15 16It returns a JSON body like the following: 17 18```json 19{ 20 "displayname": "User", 21 "threepids": [ 22 { 23 "medium": "email", 24 "address": "<user_mail_1>", 25 "added_at": 1586458409743, 26 "validated_at": 1586458409743 27 }, 28 { 29 "medium": "email", 30 "address": "<user_mail_2>", 31 "added_at": 1586458409743, 32 "validated_at": 1586458409743 33 } 34 ], 35 "avatar_url": "<avatar_url>", 36 "admin": 0, 37 "deactivated": 0, 38 "shadow_banned": 0, 39 "password_hash": "$2b$12$p9B4GkqYdRTPGD", 40 "creation_ts": 1560432506, 41 "appservice_id": null, 42 "consent_server_notice_sent": null, 43 "consent_version": null, 44 "external_ids": [ 45 { 46 "auth_provider": "<provider1>", 47 "external_id": "<user_id_provider_1>" 48 }, 49 { 50 "auth_provider": "<provider2>", 51 "external_id": "<user_id_provider_2>" 52 } 53 ], 54 "user_type": null 55} 56``` 57 58URL parameters: 59 60- `user_id`: fully-qualified user id: for example, `@user:server.com`. 61 62## Create or modify Account 63 64This API allows an administrator to create or modify a user account with a 65specific `user_id`. 66 67This api is: 68 69``` 70PUT /_synapse/admin/v2/users/<user_id> 71``` 72 73with a body of: 74 75```json 76{ 77 "password": "user_password", 78 "displayname": "User", 79 "threepids": [ 80 { 81 "medium": "email", 82 "address": "<user_mail_1>" 83 }, 84 { 85 "medium": "email", 86 "address": "<user_mail_2>" 87 } 88 ], 89 "external_ids": [ 90 { 91 "auth_provider": "<provider1>", 92 "external_id": "<user_id_provider_1>" 93 }, 94 { 95 "auth_provider": "<provider2>", 96 "external_id": "<user_id_provider_2>" 97 } 98 ], 99 "avatar_url": "<avatar_url>", 100 "admin": false, 101 "deactivated": false, 102 "user_type": null 103} 104``` 105 106To use it, you will need to authenticate by providing an `access_token` for a 107server admin: [Admin API](../usage/administration/admin_api) 108 109Returns HTTP status code: 110- `201` - When a new user object was created. 111- `200` - When a user was modified. 112 113URL parameters: 114 115- `user_id`: fully-qualified user id: for example, `@user:server.com`. 116 117Body parameters: 118 119- `password` - string, optional. If provided, the user's password is updated and all 120 devices are logged out. 121- `displayname` - string, optional, defaults to the value of `user_id`. 122- `threepids` - array, optional, allows setting the third-party IDs (email, msisdn) 123 - `medium` - string. Kind of third-party ID, either `email` or `msisdn`. 124 - `address` - string. Value of third-party ID. 125 belonging to a user. 126- `external_ids` - array, optional. Allow setting the identifier of the external identity 127 provider for SSO (Single sign-on). Details in 128 [Sample Configuration File](../usage/configuration/homeserver_sample_config.html) 129 section `sso` and `oidc_providers`. 130 - `auth_provider` - string. ID of the external identity provider. Value of `idp_id` 131 in homeserver configuration. 132 - `external_id` - string, user ID in the external identity provider. 133- `avatar_url` - string, optional, must be a 134 [MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris). 135- `admin` - bool, optional, defaults to `false`. 136- `deactivated` - bool, optional. If unspecified, deactivation state will be left 137 unchanged on existing accounts and set to `false` for new accounts. 138 A user cannot be erased by deactivating with this API. For details on 139 deactivating users see [Deactivate Account](#deactivate-account). 140- `user_type` - string or null, optional. If provided, the user type will be 141 adjusted. If `null` given, the user type will be cleared. Other 142 allowed options are: `bot` and `support`. 143 144If the user already exists then optional parameters default to the current value. 145 146In order to re-activate an account `deactivated` must be set to `false`. If 147users do not login via single-sign-on, a new `password` must be provided. 148 149## List Accounts 150 151This API returns all local user accounts. 152By default, the response is ordered by ascending user ID. 153 154``` 155GET /_synapse/admin/v2/users?from=0&limit=10&guests=false 156``` 157 158To use it, you will need to authenticate by providing an `access_token` for a 159server admin: [Admin API](../usage/administration/admin_api) 160 161A response body like the following is returned: 162 163```json 164{ 165 "users": [ 166 { 167 "name": "<user_id1>", 168 "is_guest": 0, 169 "admin": 0, 170 "user_type": null, 171 "deactivated": 0, 172 "shadow_banned": 0, 173 "displayname": "<User One>", 174 "avatar_url": null, 175 "creation_ts": 1560432668000 176 }, { 177 "name": "<user_id2>", 178 "is_guest": 0, 179 "admin": 1, 180 "user_type": null, 181 "deactivated": 0, 182 "shadow_banned": 0, 183 "displayname": "<User Two>", 184 "avatar_url": "<avatar_url>", 185 "creation_ts": 1561550621000 186 } 187 ], 188 "next_token": "100", 189 "total": 200 190} 191``` 192 193To paginate, check for `next_token` and if present, call the endpoint again 194with `from` set to the value of `next_token`. This will return a new page. 195 196If the endpoint does not return a `next_token` then there are no more users 197to paginate through. 198 199**Parameters** 200 201The following parameters should be set in the URL: 202 203- `user_id` - Is optional and filters to only return users with user IDs 204 that contain this value. This parameter is ignored when using the `name` parameter. 205- `name` - Is optional and filters to only return users with user ID localparts 206 **or** displaynames that contain this value. 207- `guests` - string representing a bool - Is optional and if `false` will **exclude** guest users. 208 Defaults to `true` to include guest users. 209- `deactivated` - string representing a bool - Is optional and if `true` will **include** deactivated users. 210 Defaults to `false` to exclude deactivated users. 211- `limit` - string representing a positive integer - Is optional but is used for pagination, 212 denoting the maximum number of items to return in this call. Defaults to `100`. 213- `from` - string representing a positive integer - Is optional but used for pagination, 214 denoting the offset in the returned results. This should be treated as an opaque value and 215 not explicitly set to anything other than the return value of `next_token` from a previous call. 216 Defaults to `0`. 217- `order_by` - The method by which to sort the returned list of users. 218 If the ordered field has duplicates, the second order is always by ascending `name`, 219 which guarantees a stable ordering. Valid values are: 220 221 - `name` - Users are ordered alphabetically by `name`. This is the default. 222 - `is_guest` - Users are ordered by `is_guest` status. 223 - `admin` - Users are ordered by `admin` status. 224 - `user_type` - Users are ordered alphabetically by `user_type`. 225 - `deactivated` - Users are ordered by `deactivated` status. 226 - `shadow_banned` - Users are ordered by `shadow_banned` status. 227 - `displayname` - Users are ordered alphabetically by `displayname`. 228 - `avatar_url` - Users are ordered alphabetically by avatar URL. 229 - `creation_ts` - Users are ordered by when the users was created in ms. 230 231- `dir` - Direction of media order. Either `f` for forwards or `b` for backwards. 232 Setting this value to `b` will reverse the above sort order. Defaults to `f`. 233 234Caution. The database only has indexes on the columns `name` and `creation_ts`. 235This means that if a different sort order is used (`is_guest`, `admin`, 236`user_type`, `deactivated`, `shadow_banned`, `avatar_url` or `displayname`), 237this can cause a large load on the database, especially for large environments. 238 239**Response** 240 241The following fields are returned in the JSON response body: 242 243- `users` - An array of objects, each containing information about an user. 244 User objects contain the following fields: 245 246 - `name` - string - Fully-qualified user ID (ex. `@user:server.com`). 247 - `is_guest` - bool - Status if that user is a guest account. 248 - `admin` - bool - Status if that user is a server administrator. 249 - `user_type` - string - Type of the user. Normal users are type `None`. 250 This allows user type specific behaviour. There are also types `support` and `bot`. 251 - `deactivated` - bool - Status if that user has been marked as deactivated. 252 - `shadow_banned` - bool - Status if that user has been marked as shadow banned. 253 - `displayname` - string - The user's display name if they have set one. 254 - `avatar_url` - string - The user's avatar URL if they have set one. 255 - `creation_ts` - integer - The user's creation timestamp in ms. 256 257- `next_token`: string representing a positive integer - Indication for pagination. See above. 258- `total` - integer - Total number of media. 259 260 261## Query current sessions for a user 262 263This API returns information about the active sessions for a specific user. 264 265The endpoints are: 266 267``` 268GET /_synapse/admin/v1/whois/<user_id> 269``` 270 271and: 272 273``` 274GET /_matrix/client/r0/admin/whois/<userId> 275``` 276 277See also: [Client Server 278API Whois](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid). 279 280To use it, you will need to authenticate by providing an `access_token` for a 281server admin: [Admin API](../usage/administration/admin_api) 282 283It returns a JSON body like the following: 284 285```json 286{ 287 "user_id": "<user_id>", 288 "devices": { 289 "": { 290 "sessions": [ 291 { 292 "connections": [ 293 { 294 "ip": "1.2.3.4", 295 "last_seen": 1417222374433, 296 "user_agent": "Mozilla/5.0 ..." 297 }, 298 { 299 "ip": "1.2.3.10", 300 "last_seen": 1417222374500, 301 "user_agent": "Dalvik/2.1.0 ..." 302 } 303 ] 304 } 305 ] 306 } 307 } 308} 309``` 310 311`last_seen` is measured in milliseconds since the Unix epoch. 312 313## Deactivate Account 314 315This API deactivates an account. It removes active access tokens, resets the 316password, and deletes third-party IDs (to prevent the user requesting a 317password reset). 318 319It can also mark the user as GDPR-erased. This means messages sent by the 320user will still be visible by anyone that was in the room when these messages 321were sent, but hidden from users joining the room afterwards. 322 323The api is: 324 325``` 326POST /_synapse/admin/v1/deactivate/<user_id> 327``` 328 329with a body of: 330 331```json 332{ 333 "erase": true 334} 335``` 336 337To use it, you will need to authenticate by providing an `access_token` for a 338server admin: [Admin API](../usage/administration/admin_api) 339 340The erase parameter is optional and defaults to `false`. 341An empty body may be passed for backwards compatibility. 342 343The following actions are performed when deactivating an user: 344 345- Try to unpind 3PIDs from the identity server 346- Remove all 3PIDs from the homeserver 347- Delete all devices and E2EE keys 348- Delete all access tokens 349- Delete all pushers 350- Delete the password hash 351- Removal from all rooms the user is a member of 352- Remove the user from the user directory 353- Reject all pending invites 354- Remove all account validity information related to the user 355 356The following additional actions are performed during deactivation if `erase` 357is set to `true`: 358 359- Remove the user's display name 360- Remove the user's avatar URL 361- Mark the user as erased 362 363The following actions are **NOT** performed. The list may be incomplete. 364 365- Remove mappings of SSO IDs 366- [Delete media uploaded](#delete-media-uploaded-by-a-user) by user (included avatar images) 367- Delete sent and received messages 368- Delete E2E cross-signing keys 369- Remove the user's creation (registration) timestamp 370- [Remove rate limit overrides](#override-ratelimiting-for-users) 371- Remove from monthly active users 372 373## Reset password 374 375Changes the password of another user. This will automatically log the user out of all their devices. 376 377The api is: 378 379``` 380POST /_synapse/admin/v1/reset_password/<user_id> 381``` 382 383with a body of: 384 385```json 386{ 387 "new_password": "<secret>", 388 "logout_devices": true 389} 390``` 391 392To use it, you will need to authenticate by providing an `access_token` for a 393server admin: [Admin API](../usage/administration/admin_api) 394 395The parameter `new_password` is required. 396The parameter `logout_devices` is optional and defaults to `true`. 397 398 399## Get whether a user is a server administrator or not 400 401The api is: 402 403``` 404GET /_synapse/admin/v1/users/<user_id>/admin 405``` 406 407To use it, you will need to authenticate by providing an `access_token` for a 408server admin: [Admin API](../usage/administration/admin_api) 409 410A response body like the following is returned: 411 412```json 413{ 414 "admin": true 415} 416``` 417 418 419## Change whether a user is a server administrator or not 420 421Note that you cannot demote yourself. 422 423The api is: 424 425``` 426PUT /_synapse/admin/v1/users/<user_id>/admin 427``` 428 429with a body of: 430 431```json 432{ 433 "admin": true 434} 435``` 436 437To use it, you will need to authenticate by providing an `access_token` for a 438server admin: [Admin API](../usage/administration/admin_api) 439 440 441## List room memberships of a user 442 443Gets a list of all `room_id` that a specific `user_id` is member. 444 445The API is: 446 447``` 448GET /_synapse/admin/v1/users/<user_id>/joined_rooms 449``` 450 451To use it, you will need to authenticate by providing an `access_token` for a 452server admin: [Admin API](../usage/administration/admin_api) 453 454A response body like the following is returned: 455 456```json 457 { 458 "joined_rooms": [ 459 "!DuGcnbhHGaSZQoNQR:matrix.org", 460 "!ZtSaPCawyWtxfWiIy:matrix.org" 461 ], 462 "total": 2 463 } 464``` 465 466The server returns the list of rooms of which the user and the server 467are member. If the user is local, all the rooms of which the user is 468member are returned. 469 470**Parameters** 471 472The following parameters should be set in the URL: 473 474- `user_id` - fully qualified: for example, `@user:server.com`. 475 476**Response** 477 478The following fields are returned in the JSON response body: 479 480- `joined_rooms` - An array of `room_id`. 481- `total` - Number of rooms. 482 483## Account Data 484Gets information about account data for a specific `user_id`. 485 486The API is: 487 488``` 489GET /_synapse/admin/v1/users/<user_id>/accountdata 490``` 491 492A response body like the following is returned: 493 494```json 495{ 496 "account_data": { 497 "global": { 498 "m.secret_storage.key.LmIGHTg5W": { 499 "algorithm": "m.secret_storage.v1.aes-hmac-sha2", 500 "iv": "fwjNZatxg==", 501 "mac": "eWh9kNnLWZUNOgnc=" 502 }, 503 "im.vector.hide_profile": { 504 "hide_profile": true 505 }, 506 "org.matrix.preview_urls": { 507 "disable": false 508 }, 509 "im.vector.riot.breadcrumb_rooms": { 510 "rooms": [ 511 "!LxcBDAsDUVAfJDEo:matrix.org", 512 "!MAhRxqasbItjOqxu:matrix.org" 513 ] 514 }, 515 "m.accepted_terms": { 516 "accepted": [ 517 "https://example.org/somewhere/privacy-1.2-en.html", 518 "https://example.org/somewhere/terms-2.0-en.html" 519 ] 520 }, 521 "im.vector.setting.breadcrumbs": { 522 "recent_rooms": [ 523 "!MAhRxqasbItqxuEt:matrix.org", 524 "!ZtSaPCawyWtxiImy:matrix.org" 525 ] 526 } 527 }, 528 "rooms": { 529 "!GUdfZSHUJibpiVqHYd:matrix.org": { 530 "m.fully_read": { 531 "event_id": "$156334540fYIhZ:matrix.org" 532 } 533 }, 534 "!tOZwOOiqwCYQkLhV:matrix.org": { 535 "m.fully_read": { 536 "event_id": "$xjsIyp4_NaVl2yPvIZs_k1Jl8tsC_Sp23wjqXPno" 537 } 538 } 539 } 540 } 541} 542``` 543 544**Parameters** 545 546The following parameters should be set in the URL: 547 548- `user_id` - fully qualified: for example, `@user:server.com`. 549 550**Response** 551 552The following fields are returned in the JSON response body: 553 554- `account_data` - A map containing the account data for the user 555 - `global` - A map containing the global account data for the user 556 - `rooms` - A map containing the account data per room for the user 557 558## User media 559 560### List media uploaded by a user 561Gets a list of all local media that a specific `user_id` has created. 562By default, the response is ordered by descending creation date and ascending media ID. 563The newest media is on top. You can change the order with parameters 564`order_by` and `dir`. 565 566The API is: 567 568``` 569GET /_synapse/admin/v1/users/<user_id>/media 570``` 571 572To use it, you will need to authenticate by providing an `access_token` for a 573server admin: [Admin API](../usage/administration/admin_api) 574 575A response body like the following is returned: 576 577```json 578{ 579 "media": [ 580 { 581 "created_ts": 100400, 582 "last_access_ts": null, 583 "media_id": "qXhyRzulkwLsNHTbpHreuEgo", 584 "media_length": 67, 585 "media_type": "image/png", 586 "quarantined_by": null, 587 "safe_from_quarantine": false, 588 "upload_name": "test1.png" 589 }, 590 { 591 "created_ts": 200400, 592 "last_access_ts": null, 593 "media_id": "FHfiSnzoINDatrXHQIXBtahw", 594 "media_length": 67, 595 "media_type": "image/png", 596 "quarantined_by": null, 597 "safe_from_quarantine": false, 598 "upload_name": "test2.png" 599 } 600 ], 601 "next_token": 3, 602 "total": 2 603} 604``` 605 606To paginate, check for `next_token` and if present, call the endpoint again 607with `from` set to the value of `next_token`. This will return a new page. 608 609If the endpoint does not return a `next_token` then there are no more 610reports to paginate through. 611 612**Parameters** 613 614The following parameters should be set in the URL: 615 616- `user_id` - string - fully qualified: for example, `@user:server.com`. 617- `limit`: string representing a positive integer - Is optional but is used for pagination, 618 denoting the maximum number of items to return in this call. Defaults to `100`. 619- `from`: string representing a positive integer - Is optional but used for pagination, 620 denoting the offset in the returned results. This should be treated as an opaque value and 621 not explicitly set to anything other than the return value of `next_token` from a previous call. 622 Defaults to `0`. 623- `order_by` - The method by which to sort the returned list of media. 624 If the ordered field has duplicates, the second order is always by ascending `media_id`, 625 which guarantees a stable ordering. Valid values are: 626 627 - `media_id` - Media are ordered alphabetically by `media_id`. 628 - `upload_name` - Media are ordered alphabetically by name the media was uploaded with. 629 - `created_ts` - Media are ordered by when the content was uploaded in ms. 630 Smallest to largest. This is the default. 631 - `last_access_ts` - Media are ordered by when the content was last accessed in ms. 632 Smallest to largest. 633 - `media_length` - Media are ordered by length of the media in bytes. 634 Smallest to largest. 635 - `media_type` - Media are ordered alphabetically by MIME-type. 636 - `quarantined_by` - Media are ordered alphabetically by the user ID that 637 initiated the quarantine request for this media. 638 - `safe_from_quarantine` - Media are ordered by the status if this media is safe 639 from quarantining. 640 641- `dir` - Direction of media order. Either `f` for forwards or `b` for backwards. 642 Setting this value to `b` will reverse the above sort order. Defaults to `f`. 643 644If neither `order_by` nor `dir` is set, the default order is newest media on top 645(corresponds to `order_by` = `created_ts` and `dir` = `b`). 646 647Caution. The database only has indexes on the columns `media_id`, 648`user_id` and `created_ts`. This means that if a different sort order is used 649(`upload_name`, `last_access_ts`, `media_length`, `media_type`, 650`quarantined_by` or `safe_from_quarantine`), this can cause a large load on the 651database, especially for large environments. 652 653**Response** 654 655The following fields are returned in the JSON response body: 656 657- `media` - An array of objects, each containing information about a media. 658 Media objects contain the following fields: 659 - `created_ts` - integer - Timestamp when the content was uploaded in ms. 660 - `last_access_ts` - integer - Timestamp when the content was last accessed in ms. 661 - `media_id` - string - The id used to refer to the media. 662 - `media_length` - integer - Length of the media in bytes. 663 - `media_type` - string - The MIME-type of the media. 664 - `quarantined_by` - string - The user ID that initiated the quarantine request 665 for this media. 666 - `safe_from_quarantine` - bool - Status if this media is safe from quarantining. 667 - `upload_name` - string - The name the media was uploaded with. 668- `next_token`: integer - Indication for pagination. See above. 669- `total` - integer - Total number of media. 670 671### Delete media uploaded by a user 672 673This API deletes the *local* media from the disk of your own server 674that a specific `user_id` has created. This includes any local thumbnails. 675 676This API will not affect media that has been uploaded to external 677media repositories (e.g https://github.com/turt2live/matrix-media-repo/). 678 679By default, the API deletes media ordered by descending creation date and ascending media ID. 680The newest media is deleted first. You can change the order with parameters 681`order_by` and `dir`. If no `limit` is set the API deletes `100` files per request. 682 683The API is: 684 685``` 686DELETE /_synapse/admin/v1/users/<user_id>/media 687``` 688 689To use it, you will need to authenticate by providing an `access_token` for a 690server admin: [Admin API](../usage/administration/admin_api) 691 692A response body like the following is returned: 693 694```json 695{ 696 "deleted_media": [ 697 "abcdefghijklmnopqrstuvwx" 698 ], 699 "total": 1 700} 701``` 702 703The following fields are returned in the JSON response body: 704 705* `deleted_media`: an array of strings - List of deleted `media_id` 706* `total`: integer - Total number of deleted `media_id` 707 708**Note**: There is no `next_token`. This is not useful for deleting media, because 709after deleting media the remaining media have a new order. 710 711**Parameters** 712 713This API has the same parameters as 714[List media uploaded by a user](#list-media-uploaded-by-a-user). 715With the parameters you can for example limit the number of files to delete at once or 716delete largest/smallest or newest/oldest files first. 717 718## Login as a user 719 720Get an access token that can be used to authenticate as that user. Useful for 721when admins wish to do actions on behalf of a user. 722 723The API is: 724 725``` 726POST /_synapse/admin/v1/users/<user_id>/login 727{} 728``` 729 730An optional `valid_until_ms` field can be specified in the request body as an 731integer timestamp that specifies when the token should expire. By default tokens 732do not expire. 733 734A response body like the following is returned: 735 736```json 737{ 738 "access_token": "<opaque_access_token_string>" 739} 740``` 741 742This API does *not* generate a new device for the user, and so will not appear 743their `/devices` list, and in general the target user should not be able to 744tell they have been logged in as. 745 746To expire the token call the standard `/logout` API with the token. 747 748Note: The token will expire if the *admin* user calls `/logout/all` from any 749of their devices, but the token will *not* expire if the target user does the 750same. 751 752 753## User devices 754 755### List all devices 756Gets information about all devices for a specific `user_id`. 757 758The API is: 759 760``` 761GET /_synapse/admin/v2/users/<user_id>/devices 762``` 763 764To use it, you will need to authenticate by providing an `access_token` for a 765server admin: [Admin API](../usage/administration/admin_api) 766 767A response body like the following is returned: 768 769```json 770{ 771 "devices": [ 772 { 773 "device_id": "QBUAZIFURK", 774 "display_name": "android", 775 "last_seen_ip": "1.2.3.4", 776 "last_seen_ts": 1474491775024, 777 "user_id": "<user_id>" 778 }, 779 { 780 "device_id": "AUIECTSRND", 781 "display_name": "ios", 782 "last_seen_ip": "1.2.3.5", 783 "last_seen_ts": 1474491775025, 784 "user_id": "<user_id>" 785 } 786 ], 787 "total": 2 788} 789``` 790 791**Parameters** 792 793The following parameters should be set in the URL: 794 795- `user_id` - fully qualified: for example, `@user:server.com`. 796 797**Response** 798 799The following fields are returned in the JSON response body: 800 801- `devices` - An array of objects, each containing information about a device. 802 Device objects contain the following fields: 803 804 - `device_id` - Identifier of device. 805 - `display_name` - Display name set by the user for this device. 806 Absent if no name has been set. 807 - `last_seen_ip` - The IP address where this device was last seen. 808 (May be a few minutes out of date, for efficiency reasons). 809 - `last_seen_ts` - The timestamp (in milliseconds since the unix epoch) when this 810 devices was last seen. (May be a few minutes out of date, for efficiency reasons). 811 - `user_id` - Owner of device. 812 813- `total` - Total number of user's devices. 814 815### Delete multiple devices 816Deletes the given devices for a specific `user_id`, and invalidates 817any access token associated with them. 818 819The API is: 820 821``` 822POST /_synapse/admin/v2/users/<user_id>/delete_devices 823 824{ 825 "devices": [ 826 "QBUAZIFURK", 827 "AUIECTSRND" 828 ], 829} 830``` 831 832To use it, you will need to authenticate by providing an `access_token` for a 833server admin: [Admin API](../usage/administration/admin_api) 834 835An empty JSON dict is returned. 836 837**Parameters** 838 839The following parameters should be set in the URL: 840 841- `user_id` - fully qualified: for example, `@user:server.com`. 842 843The following fields are required in the JSON request body: 844 845- `devices` - The list of device IDs to delete. 846 847### Show a device 848Gets information on a single device, by `device_id` for a specific `user_id`. 849 850The API is: 851 852``` 853GET /_synapse/admin/v2/users/<user_id>/devices/<device_id> 854``` 855 856To use it, you will need to authenticate by providing an `access_token` for a 857server admin: [Admin API](../usage/administration/admin_api) 858 859A response body like the following is returned: 860 861```json 862{ 863 "device_id": "<device_id>", 864 "display_name": "android", 865 "last_seen_ip": "1.2.3.4", 866 "last_seen_ts": 1474491775024, 867 "user_id": "<user_id>" 868} 869``` 870 871**Parameters** 872 873The following parameters should be set in the URL: 874 875- `user_id` - fully qualified: for example, `@user:server.com`. 876- `device_id` - The device to retrieve. 877 878**Response** 879 880The following fields are returned in the JSON response body: 881 882- `device_id` - Identifier of device. 883- `display_name` - Display name set by the user for this device. 884 Absent if no name has been set. 885- `last_seen_ip` - The IP address where this device was last seen. 886 (May be a few minutes out of date, for efficiency reasons). 887- `last_seen_ts` - The timestamp (in milliseconds since the unix epoch) when this 888 devices was last seen. (May be a few minutes out of date, for efficiency reasons). 889- `user_id` - Owner of device. 890 891### Update a device 892Updates the metadata on the given `device_id` for a specific `user_id`. 893 894The API is: 895 896``` 897PUT /_synapse/admin/v2/users/<user_id>/devices/<device_id> 898 899{ 900 "display_name": "My other phone" 901} 902``` 903 904To use it, you will need to authenticate by providing an `access_token` for a 905server admin: [Admin API](../usage/administration/admin_api) 906 907An empty JSON dict is returned. 908 909**Parameters** 910 911The following parameters should be set in the URL: 912 913- `user_id` - fully qualified: for example, `@user:server.com`. 914- `device_id` - The device to update. 915 916The following fields are required in the JSON request body: 917 918- `display_name` - The new display name for this device. If not given, 919 the display name is unchanged. 920 921### Delete a device 922Deletes the given `device_id` for a specific `user_id`, 923and invalidates any access token associated with it. 924 925The API is: 926 927``` 928DELETE /_synapse/admin/v2/users/<user_id>/devices/<device_id> 929 930{} 931``` 932 933To use it, you will need to authenticate by providing an `access_token` for a 934server admin: [Admin API](../usage/administration/admin_api) 935 936An empty JSON dict is returned. 937 938**Parameters** 939 940The following parameters should be set in the URL: 941 942- `user_id` - fully qualified: for example, `@user:server.com`. 943- `device_id` - The device to delete. 944 945## List all pushers 946Gets information about all pushers for a specific `user_id`. 947 948The API is: 949 950``` 951GET /_synapse/admin/v1/users/<user_id>/pushers 952``` 953 954To use it, you will need to authenticate by providing an `access_token` for a 955server admin: [Admin API](../usage/administration/admin_api) 956 957A response body like the following is returned: 958 959```json 960{ 961 "pushers": [ 962 { 963 "app_display_name":"HTTP Push Notifications", 964 "app_id":"m.http", 965 "data": { 966 "url":"example.com" 967 }, 968 "device_display_name":"pushy push", 969 "kind":"http", 970 "lang":"None", 971 "profile_tag":"", 972 "pushkey":"a@example.com" 973 } 974 ], 975 "total": 1 976} 977``` 978 979**Parameters** 980 981The following parameters should be set in the URL: 982 983- `user_id` - fully qualified: for example, `@user:server.com`. 984 985**Response** 986 987The following fields are returned in the JSON response body: 988 989- `pushers` - An array containing the current pushers for the user 990 991 - `app_display_name` - string - A string that will allow the user to identify 992 what application owns this pusher. 993 994 - `app_id` - string - This is a reverse-DNS style identifier for the application. 995 Max length, 64 chars. 996 997 - `data` - A dictionary of information for the pusher implementation itself. 998 999 - `url` - string - Required if `kind` is `http`. The URL to use to send 1000 notifications to. 1001 1002 - `format` - string - The format to use when sending notifications to the 1003 Push Gateway. 1004 1005 - `device_display_name` - string - A string that will allow the user to identify 1006 what device owns this pusher. 1007 1008 - `profile_tag` - string - This string determines which set of device specific rules 1009 this pusher executes. 1010 1011 - `kind` - string - The kind of pusher. "http" is a pusher that sends HTTP pokes. 1012 - `lang` - string - The preferred language for receiving notifications 1013 (e.g. 'en' or 'en-US') 1014 1015 - `profile_tag` - string - This string determines which set of device specific rules 1016 this pusher executes. 1017 1018 - `pushkey` - string - This is a unique identifier for this pusher. 1019 Max length, 512 bytes. 1020 1021- `total` - integer - Number of pushers. 1022 1023See also the 1024[Client-Server API Spec on pushers](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-pushers). 1025 1026## Controlling whether a user is shadow-banned 1027 1028Shadow-banning is a useful tool for moderating malicious or egregiously abusive users. 1029A shadow-banned users receives successful responses to their client-server API requests, 1030but the events are not propagated into rooms. This can be an effective tool as it 1031(hopefully) takes longer for the user to realise they are being moderated before 1032pivoting to another account. 1033 1034Shadow-banning a user should be used as a tool of last resort and may lead to confusing 1035or broken behaviour for the client. A shadow-banned user will not receive any 1036notification and it is generally more appropriate to ban or kick abusive users. 1037A shadow-banned user will be unable to contact anyone on the server. 1038 1039To shadow-ban a user the API is: 1040 1041``` 1042POST /_synapse/admin/v1/users/<user_id>/shadow_ban 1043``` 1044 1045To un-shadow-ban a user the API is: 1046 1047``` 1048DELETE /_synapse/admin/v1/users/<user_id>/shadow_ban 1049``` 1050 1051To use it, you will need to authenticate by providing an `access_token` for a 1052server admin: [Admin API](../usage/administration/admin_api) 1053 1054An empty JSON dict is returned in both cases. 1055 1056**Parameters** 1057 1058The following parameters should be set in the URL: 1059 1060- `user_id` - The fully qualified MXID: for example, `@user:server.com`. The user must 1061 be local. 1062 1063## Override ratelimiting for users 1064 1065This API allows to override or disable ratelimiting for a specific user. 1066There are specific APIs to set, get and delete a ratelimit. 1067 1068### Get status of ratelimit 1069 1070The API is: 1071 1072``` 1073GET /_synapse/admin/v1/users/<user_id>/override_ratelimit 1074``` 1075 1076To use it, you will need to authenticate by providing an `access_token` for a 1077server admin: [Admin API](../usage/administration/admin_api) 1078 1079A response body like the following is returned: 1080 1081```json 1082{ 1083 "messages_per_second": 0, 1084 "burst_count": 0 1085} 1086``` 1087 1088**Parameters** 1089 1090The following parameters should be set in the URL: 1091 1092- `user_id` - The fully qualified MXID: for example, `@user:server.com`. The user must 1093 be local. 1094 1095**Response** 1096 1097The following fields are returned in the JSON response body: 1098 1099- `messages_per_second` - integer - The number of actions that can 1100 be performed in a second. `0` mean that ratelimiting is disabled for this user. 1101- `burst_count` - integer - How many actions that can be performed before 1102 being limited. 1103 1104If **no** custom ratelimit is set, an empty JSON dict is returned. 1105 1106```json 1107{} 1108``` 1109 1110### Set ratelimit 1111 1112The API is: 1113 1114``` 1115POST /_synapse/admin/v1/users/<user_id>/override_ratelimit 1116``` 1117 1118To use it, you will need to authenticate by providing an `access_token` for a 1119server admin: [Admin API](../usage/administration/admin_api) 1120 1121A response body like the following is returned: 1122 1123```json 1124{ 1125 "messages_per_second": 0, 1126 "burst_count": 0 1127} 1128``` 1129 1130**Parameters** 1131 1132The following parameters should be set in the URL: 1133 1134- `user_id` - The fully qualified MXID: for example, `@user:server.com`. The user must 1135 be local. 1136 1137Body parameters: 1138 1139- `messages_per_second` - positive integer, optional. The number of actions that can 1140 be performed in a second. Defaults to `0`. 1141- `burst_count` - positive integer, optional. How many actions that can be performed 1142 before being limited. Defaults to `0`. 1143 1144To disable users' ratelimit set both values to `0`. 1145 1146**Response** 1147 1148The following fields are returned in the JSON response body: 1149 1150- `messages_per_second` - integer - The number of actions that can 1151 be performed in a second. 1152- `burst_count` - integer - How many actions that can be performed before 1153 being limited. 1154 1155### Delete ratelimit 1156 1157The API is: 1158 1159``` 1160DELETE /_synapse/admin/v1/users/<user_id>/override_ratelimit 1161``` 1162 1163To use it, you will need to authenticate by providing an `access_token` for a 1164server admin: [Admin API](../usage/administration/admin_api) 1165 1166An empty JSON dict is returned. 1167 1168```json 1169{} 1170``` 1171 1172**Parameters** 1173 1174The following parameters should be set in the URL: 1175 1176- `user_id` - The fully qualified MXID: for example, `@user:server.com`. The user must 1177 be local. 1178 1179### Check username availability 1180 1181Checks to see if a username is available, and valid, for the server. See [the client-server 1182API](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available) 1183for more information. 1184 1185This endpoint will work even if registration is disabled on the server, unlike 1186`/_matrix/client/r0/register/available`. 1187 1188The API is: 1189 1190``` 1191GET /_synapse/admin/v1/username_available?username=$localpart 1192``` 1193 1194The request and response format is the same as the [/_matrix/client/r0/register/available](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available) API. 1195 1196To use it, you will need to authenticate by providing an `access_token` for a 1197server admin: [Admin API](../usage/administration/admin_api) 1198