Require explicit un-banning
This commit is contained in:
Daniel Wagner-Hall
review.rocks
parent
c69481d67a
commit
2e46b587b8
3 changed files with 169 additions and 3 deletions
|
|
@ -24,7 +24,7 @@ paths:
|
||||||
description: |-
|
description: |-
|
||||||
Ban a user in the room. If the user is currently in the room, also kick them.
|
Ban a user in the room. If the user is currently in the room, also kick them.
|
||||||
|
|
||||||
When a user is banned from a room, they may not join it until they are unbanned.
|
When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
|
||||||
|
|
||||||
The caller must have the required power level in order to perform this operation.
|
The caller must have the required power level in order to perform this operation.
|
||||||
security:
|
security:
|
||||||
|
|
@ -76,3 +76,55 @@ paths:
|
||||||
}
|
}
|
||||||
tags:
|
tags:
|
||||||
- Room membership
|
- Room membership
|
||||||
|
"/rooms/{roomId}/unban":
|
||||||
|
post:
|
||||||
|
summary: Unban a user from the room.
|
||||||
|
description: |-
|
||||||
|
Unban a user from the room. This allows them to be invited to the room,
|
||||||
|
and join if they would otherwise be allowed to join according to its join rules.
|
||||||
|
|
||||||
|
The caller must have the required power level in order to perform this operation.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The room identifier (not alias) from which the user should be unbanned.
|
||||||
|
required: true
|
||||||
|
x-example: "!e42d8c:matrix.org"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: |-
|
||||||
|
{
|
||||||
|
"user_id": "@cheeky_monkey:matrix.org"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
description: The fully qualified user ID of the user being unbanned.
|
||||||
|
required: ["user_id"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The user has been unbanned from the room.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
403:
|
||||||
|
description: |-
|
||||||
|
You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
|
||||||
|
|
||||||
|
- The unbanner's power level is insufficient to unban users from the room.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{
|
||||||
|
"errcode": "M_FORBIDDEN",
|
||||||
|
"error": "You do not have a high enough power level to unban from this room."
|
||||||
|
}
|
||||||
|
tags:
|
||||||
|
- Room membership
|
||||||
|
|
|
||||||
77
api/client-server/kicking.yaml
Normal file
77
api/client-server/kicking.yaml
Normal file
|
|
@ -0,0 +1,77 @@
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Client-Server Room Kicking API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
accessToken:
|
||||||
|
type: apiKey
|
||||||
|
description: The user_id or application service access_token
|
||||||
|
name: access_token
|
||||||
|
in: query
|
||||||
|
paths:
|
||||||
|
"/rooms/{roomId}/kick":
|
||||||
|
post:
|
||||||
|
summary: Kick a user from the room.
|
||||||
|
description: |-
|
||||||
|
Kick a user from the room.
|
||||||
|
|
||||||
|
The caller must have the required power level in order to perform this operation.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The room identifier (not alias) from which the user should be kicked.
|
||||||
|
required: true
|
||||||
|
x-example: "!e42d8c:matrix.org"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: |-
|
||||||
|
{
|
||||||
|
"reason": "Telling unfunny jokes",
|
||||||
|
"user_id": "@cheeky_monkey:matrix.org"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
description: The fully qualified user ID of the user being kicked.
|
||||||
|
reason:
|
||||||
|
type: string
|
||||||
|
description: The reason the user has been kicked.
|
||||||
|
required: ["user_id"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The user has been kicked from the room.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
403:
|
||||||
|
description: |-
|
||||||
|
You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
|
||||||
|
|
||||||
|
- The kicker is not currently in the room.
|
||||||
|
- The kickee is not currently in the room.
|
||||||
|
- The kicker's power level is insufficient to kick users from the room.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{
|
||||||
|
"errcode": "M_FORBIDDEN",
|
||||||
|
"error": "You do not have a high enough power level to kick from this room."
|
||||||
|
}
|
||||||
|
tags:
|
||||||
|
- Room membership
|
||||||
|
|
@ -914,10 +914,42 @@ following values:
|
||||||
``invite``
|
``invite``
|
||||||
This room can only be joined if you were invited.
|
This room can only be joined if you were invited.
|
||||||
|
|
||||||
|
The allowable state transitions of membership are::
|
||||||
|
|
||||||
|
/ban
|
||||||
|
+------------------------------------------------------+
|
||||||
|
| |
|
||||||
|
| +----------------+ +----------------+ |
|
||||||
|
| | /leave | | | |
|
||||||
|
| | v v | |
|
||||||
|
/invite +--------+ +-------+ | |
|
||||||
|
------------>| invite |<----------| leave |----+ | |
|
||||||
|
+--------+ /invite +-------+ | | |
|
||||||
|
| | ^ | | |
|
||||||
|
| | | | | |
|
||||||
|
/join | +---------------+ | | | |
|
||||||
|
| | /join if | | | |
|
||||||
|
| | join_rules | | /ban | /unban |
|
||||||
|
| | public /leave | | | |
|
||||||
|
v v or | | | |
|
||||||
|
+------+ /kick | | | |
|
||||||
|
------------>| join |-------------------+ | | |
|
||||||
|
/join +------+ v | |
|
||||||
|
if | +-----+ | |
|
||||||
|
join_rules +-------------------------->| ban |-----+ |
|
||||||
|
public /ban +-----+ |
|
||||||
|
^ ^ |
|
||||||
|
| | |
|
||||||
|
----------------------------------------------+ +----------------------+
|
||||||
|
/ban
|
||||||
|
|
||||||
|
|
||||||
{{inviting_http_api}}
|
{{inviting_http_api}}
|
||||||
|
|
||||||
{{joining_http_api}}
|
{{joining_http_api}}
|
||||||
|
|
||||||
|
{{kicking_http_api}}
|
||||||
|
|
||||||
{{banning_http_api}}
|
{{banning_http_api}}
|
||||||
|
|
||||||
Leaving rooms
|
Leaving rooms
|
||||||
|
|
@ -947,8 +979,7 @@ to |/rooms/<room_id>/ban|_ with::
|
||||||
"reason": "string: <reason for the ban>"
|
"reason": "string: <reason for the ban>"
|
||||||
}
|
}
|
||||||
|
|
||||||
Banning a user adjusts the banned member's membership state to ``ban`` and
|
Banning a user adjusts the banned member's membership state to ``ban``.
|
||||||
adjusts the power level of this event to a level higher than the banned person.
|
|
||||||
Like with other membership changes, a user can directly adjust the target
|
Like with other membership changes, a user can directly adjust the target
|
||||||
member's state, by making a request to
|
member's state, by making a request to
|
||||||
``/rooms/<room id>/state/m.room.member/<user id>``::
|
``/rooms/<room id>/state/m.room.member/<user id>``::
|
||||||
|
|
@ -957,6 +988,9 @@ member's state, by making a request to
|
||||||
"membership": "ban"
|
"membership": "ban"
|
||||||
}
|
}
|
||||||
|
|
||||||
|
A user must be explicitly unbanned with a request to |/rooms/<room_id>/unban|_
|
||||||
|
before they can re-join the room or be re-invited.
|
||||||
|
|
||||||
Listing rooms
|
Listing rooms
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
@ -1048,3 +1082,6 @@ have to wait in milliseconds before they can try again.
|
||||||
.. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
|
.. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
|
||||||
.. _/rooms/<room_id>/ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban
|
.. _/rooms/<room_id>/ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban
|
||||||
|
|
||||||
|
.. |/rooms/<room_id>/unban| replace:: ``/rooms/<room_id>/unban``
|
||||||
|
.. _/rooms/<room_id>/unban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-unban
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue