Update api.md

docs/api.md

@@ -12,8 +12,7 @@ expect consumers of this plugin to use WebSockets, but you can probably use what
 1. Signal your attachment to the Janus plugin. See the [Janus documentation][janus-transports] on how to attach to a
    plugin. This plugin's name is `janus.plugin.sfu`.
 
-2. Determine your user ID. This should be a unique ID that nobody else is likely to share. In the future, we will actually
-   have authentication; as it stands just pick a big random ID and pray for no collisions.
+2. Determine your user ID. This should be a unique ID that nobody else is likely to share. Pick a big random ID and pray for no collisions.
 
 3. Create an RTC connection.
 
@@ -55,21 +54,31 @@ join a room. You can only join one room with any connection.
     "kind": "join",
     "room_id": room ID,
     "user_id": user ID,
-    "subscribe": [none|subscription object]
+    "subscribe": [none|subscription object],
+    "token": [none|string]
 }
 ```
 
 If `subscription: {...}` is passed, you will synchronously configure an initial subscription to the traffic that you
 want to get pushed through your connection. The format of the subscription should be identical to that in the
-[subscribe](#subscribe) message, below.
+[subscribe](#subscribe) message `what`, below.
+
+`token` is a JWT to verify you allowed to connect to the room `room_id`, this is verified if you specified an `auth_key` to a public RSA key in DER format in `janus.plugin.sfu.cfg`. The JWT contains the following claims:
+
+```
+{kick_users: [true|false], join_hub: true, room_ids: ["room_alpha"]}
+```
+
+`room_ids` is optional. If `room_ids` is not specified, you can connect to the room `room_id` if `join_hub` is `true`.
+If `room_ids` is specified, `room_id` needs to be listed in `room_ids` to be able to connect to the room.
 
 The response will return the users on the server in the room you joined, as below, including yourself. If you `subscribe`d to a user's media, you will also get a JSEP offer you can use to get that user's RTP traffic.
 
 ```
 {
     "success": true,
     "response": {
-        "users": {room_alpha: ["123", "789"]}
+        "users": {"room_alpha": ["123", "789"]}
     }
 }
 ```
@@ -81,9 +90,12 @@ Subscribes to some kind of traffic coming from the server.
 ```
 {
     "kind": "subscribe",
-    "notifications": [none|boolean],
-    "data": [none|boolean],
-    "media": [none|user ID]
+    "what": {
+        "notifications": [none|boolean],
+        "data": [none|boolean],
+        "media": [none|user ID]
+    },
+    "token": [none|string]
 }
 ```
 
@@ -93,6 +105,22 @@ If `data` is `true`, you will get all data traffic from other users in your room
 
 If `media` is a user ID, the server will respond with a JSEP offer which you can use to establish a connection suitable to receive audio and video RTP data coming from that user ID.
 
+If `token` is specified, `room_ids` claim is present in the JWT and `auth_key` configured, the following security check is done:
+the user is allowed to subscribe to a publisher user ID (specified in `media`) if this publisher is connected to a room listed in the JWT `room_ids`.
+
+### Kick
+
+Kick another user from the room. You need a token with the `kick_users: true` claim.
+
+```
+{
+    "kind": "kick",
+    "room_id": room ID,
+    "user_id": user ID,
+    "token": [none|string]
+}
+```
+
 ### Block
 
 Blocks another user. Blocks are bidirectional; the targeted user won't get your data, audio, or video, and you won't get