added some documentation for the tokens API

API.md

@@ -10,6 +10,48 @@ It must be accessed using one of the following domains as the Host header:
 
 All requests require an OAuth3 token in the request headers.
 
+## Tokens
+
+Some of the functionality of goldilocks requires the use of OAuth3 tokens to
+perform tasks like setting DNS records. Management of these tokens can be done
+using the following APIs.
+
+### Get A Single Token
+  * **URL** `/api/goldilocks@daplie.com/tokens/:id`
+  * **Method** `GET`
+  * **Reponse**: The token matching the specified ID. Has the following properties.
+    * `id`: The hash used to identify the token. Based on several of the fields
+      inside the decoded token.
+    * `provider_uri`: The URI for the one who issued the token. Should be the same
+      as the `iss` field inside the decoded token.
+    * `client_uri`: The URI for the app authorized to use the token. Should be the
+      same as the `azp` field inside the decoded token.
+    * `scope`: The list of permissions granted by the token. Should be the same
+      as the `scp` field inside the decoded token.
+    * `access_token`: The encoded JWT.
+    * `token`: The decoded token.
+
+### Get All Tokens
+  * **URL** `/api/goldilocks@daplie.com/tokens`
+  * **Method** `GET`
+  * **Reponse**: An array of the tokens stored. Each item looks the same as if it
+    had been requested individually.
+
+### Save New Token
+  * **URL** `/api/goldilocks@daplie.com/tokens`
+  * **Method** `POST`
+  * **Body**: An object similar to an OAuth3 session used by the javascript
+    library. The only important fields are `refresh_token` or `access_token`, and
+    `refresh_token` will be used before `access_token`. (This is because the
+    `access_token` usually expires quickly, making it meaningless to store.)
+  * **Reponse**: The response looks the same as a single GET request.
+
+### Delete Token
+  * **URL** `/api/goldilocks@daplie.com/tokens/:id`
+  * **Method** `DELETE`
+  * **Reponse**: Either `{"success":true}` or `{"success":false}`, depending on
+    whether the token was present before the request.
+
 ## Config
 
 ### Get All Settings