Documentation updates

README.md

@@ -39,7 +39,7 @@ Here are some of the configuration options you must set when provisioning a new
  * **Encryption keys**: Encryption keys will be autogenerated if not present. They can be reset using `rake keys:generate`. If `ENV['RSA_KEY']` is set, it will be used in place of the `*.pem` files. Useful for environments like Heroku, where file system access is not allowed.
   * `ENV['MONGO_URL']`: URL pointing to running MongoDB instance.
   * `ENV['DEVISE_SECRET']`: Used for devise. Use `rake secret` to generate a new value.
-  * `ENV['MQTT_URL']`: URL of running [MQTT gateway](https://github.com/FarmBot/mqtt-gateway). This is required so that Farmbot can know where to connect when given an authorization token. 
+  * `ENV['MQTT_URL']`: URL of running [MQTT gateway](https://github.com/FarmBot/mqtt-gateway). This is required so that Farmbot can know where to connect when given an authorization token.
 
 The frontend (and asset management) are very much in a transitional state. We're experimenting with Gulp as an alternative
 
@@ -51,6 +51,59 @@ Please run them before submitting pull requests.
 
  * `bundle exec rspec spec`
 
+# Generating an API token
+
+You must pass a `token` string into most HTTP requests under the `Authorization: ` request header.
+
+Here's what a response looks like when you request a token:
+
+```json
+{
+    "token": {
+        "unencoded": {
+            "sub": "test123@test.com",
+            "iat": 1459109728,
+            "jti": "922a5a0d-0b3a-4767-9318-1e41ae600352",
+            "iss": "http://localhost:3000/",
+            "exp": 1459455328,
+            "mqtt": "localhost",
+            "bot": "aa7bb37f-5ba3-4654-b2e4-58ed5746508c"
+        },
+        "encoded": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ0ZXN0MTIzQHRlc3QuY29tIiwiaWF0IjoxNDU5MTA5NzI4LCJqdGkiOiI5MjJhNWEwZC0wYjNhLTQ3NjctOTMxOC0xZTQxYWU2MDAzNTIiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAvIiwiZXhwIjoxNDU5NDU1MzI4LCJtcXR0IjoibG9jYWxob3N0IiwiYm90IjoiYWE3YmIzN2YtNWJhMy00NjU0LWIyZTQtNThlZDU3NDY1MDhjIn0.KpkNGR9YH68AF3iHP48GormqXzspBJrDGm23aMFGyL_eRIN8iKzy4gw733SaJgFjmebJOqZkz3cly9P5ZpCKwlaxAyn9RvfjQgFcUK0mywWAAvKp5lHfOFLhBBGICTW1r4HcZBgY1zTzVBw4BqS4zM7Y0BAAsflYRdl4dDRG_236p9ETCj0MSYxFagfLLLq0W63943jSJtNwv_nzfqi3TTi0xASB14k5vYMzUDXrC-Z2iBdgmwAYUZUVTi2HsfzkIkRcTZGE7l-rF6lvYKIiKpYx23x_d7xGjnQb8hqbDmLDRXZJnSBY3zGY7oEURxncGBMUp4F_Yaf3ftg4Ry7CiA"
+    }
+}
+```
+
+**Important:** The response is provided as JSON for human readability. For you `Authorization` header, you will only be using `data.token.encoded`. In this example, it's the string starting with `eyJ0eXAiOiJ...`
+
+## Via CURL
+
+```
+curl -H "Content-Type: application/json" \
+     -X POST \
+     -d '{"user":{"email":"test123@test.com","password":"password123"}}' \
+     https://my.farmbot.io/api/tokens
+```
+
+## Via JQuery
+
+Since the API supports [CORS](http://enable-cors.org/), you can generate your token right in the browser.
+
+Here's an example:
+
+```javascript
+$.ajax({
+    url: "https://my.farmbot.io/api/tokens",
+    type: "POST",
+    data: JSON.stringify({user: {email: 'admin@admin.com', password: 'password123'}}),
+    contentType: "application/json"
+})
+.then(function(data){
+  // You can now use your token:
+  var MY_SHINY_TOKEN = data.token.encoded;
+});
+```
+
 # How to Contribute
 
  * Pull requests are always appreciated, but *please*