From 5f14a797cd951b0055ab7fa7af83356908df8a4e Mon Sep 17 00:00:00 2001
From: or-else <or.else@gmail.com>
Date: Mon, 21 May 2018 11:17:25 -0700
Subject: [PATCH] clarifications and formatting fixes

---
 docs/API.md      | 28 ++++++++++++++--------------
 keygen/README.md |  7 +++++++
 keygen/keygen.go |  2 +-
 3 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index 8d1cf902..24e97c70 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -37,13 +37,13 @@ Server-issued message IDs are base-10 sequential numbers starting at 1. They gua
 
 ## Connecting to the server
 
-Client establishes a connection to the server over HTTP. Server offers two end points:
+Client establishes a connection to the server over HTTP(S). Server offers two end points:
  * `/v0/channels` for websocket connections
  * `/v0/channels/lp` for long polling
 
-`v0` denotes API version (currently zero). Every HTTP request must include the API key. It may be included in the URL as `...?apikey=<YOUR_API_KEY>`, in the request body as `apikey=<YOUR_API_KEY>`, or in the HTTP header `X-Tinode-APIKey: <YOUR_API_KEY>`.
+`v0` denotes API version (currently zero). Every HTTP(S) request must include the API key. It may be included in the URL as `...?apikey=<YOUR_API_KEY>`, in the request body as `apikey=<YOUR_API_KEY>`, or in the HTTP header `X-Tinode-APIKey: <YOUR_API_KEY>`. A default key is included in every demo app for convenience. Generate your own key using [`keygen` utility](../keygen).
 
-Once the connection is opened, the client must issue a `{hi}` message to the server. Server responds with a `{ctrl}` message which maybe an error message. The `params` field of the response contains server's protocol version: `"params":{"ver":"0.7"}`. `params` may include other values.
+Once the connection is opened, the client must issue a `{hi}` message to the server. Server responds with a `{ctrl}` message which maybe an error message. The `params` field of the response contains server's protocol version `"params":{"ver":"0.15"}` and may include other values.
 
 ### Websocket
 
@@ -835,35 +835,35 @@ The format of the `public` field is expected to be a [vCard](https://en.wikipedi
 vcard: {
   fn: "John Doe", // string, formatted name
   n: {
-	surname: "Miner", // last of family name
+    surname: "Miner", // last of family name
     given: "Coal", // first or given name
     additional: "Diamond", // additional name, such as middle name or patronymic or nickname.
     prefix: "Dr.", // prefix, such as homnorary title or gender designation.
     suffix: "Jr.", // suffix, such as 'Jr' or 'II'
-  }, // object, user's structured name'
+  }, // object, user's structured name
   org: "Most Evil Corp", // string, name of the organization the user belongs to.
   title: "CEO", // string, job title
   tel: [
     {
-	  type: "HOME", // string, optional designation
+      type: "HOME", // string, optional designation
       uri: "tel:+17025551234" // string, phone number
-	}, ...
+    }, ...
   ], // array of objects, list of phone numbers associated with the user 
   email: [
     {
-	  type: "WORK", // string, optional designation
+      type: "WORK", // string, optional designation
       uri: "email:alice@example.com", // string, email address
-	}, ...
+    }, ...
   ], // array of objects, list of user's email addresses
   impp: [
-	{
-	  type: "OTHER",
+    {
+      type: "OTHER",
       uri: "tinode:usrRkDVe0PYDOo", // string, email address
-	}, ...
+    }, ...
   ], // array of objects, list of user's IM handles
   photo: {
-	type: "jpeg", // image type
-	data: "..." // base64-encoded binary image data
+    type: "jpeg", // image type
+    data: "..." // base64-encoded binary image data
   } // object, avatar photo. Java does not have a useful bitmap class, so keeping it as bits here.
 }
 ```
diff --git a/keygen/README.md b/keygen/README.md
index 308b0bfe..33f5a509 100644
--- a/keygen/README.md
+++ b/keygen/README.md
@@ -1,3 +1,10 @@
 # keygen: API key generator
 
 A command-line utility to generate an API key for [Tinode server](../server/)
+
+Parameters:
+
+ * `sequence`: Sequential number of the API key. This value can be used to reject previously issued keys.
+ * `isroot`: Currently unused. Intended to designate key of a system administrator.
+ * `validate`: Key to validate: check previously issued key for validity.
+ * `salt`: [HMAC](https://en.wikipedia.org/wiki/HMAC) salt, 32 random bytes base64 encoded or `auto` to automatically generate salt.
diff --git a/keygen/keygen.go b/keygen/keygen.go
index f6c97dfb..838663fb 100644
--- a/keygen/keygen.go
+++ b/keygen/keygen.go
@@ -15,7 +15,7 @@ import (
 
 // Generate API key
 // Composition:
-//  [1:algorithm version][4:deprecated (used to be expiration time)][2:key sequence][1:isRoot][16:signature] = 24 bytes
+//  [1:algorithm version][4:deprecated (used to be application ID)][2:key sequence][1:isRoot][16:signature] = 24 bytes
 // convertible to base64 without padding
 // All integers are little-endian
 func main() {