From 0ef845f2d502b636c70490700e6093c0cce45c60 Mon Sep 17 00:00:00 2001 From: tigerbot Date: Thu, 26 Oct 2017 12:07:27 -0600 Subject: [PATCH] added some documentation for the tokens API --- API.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/API.md b/API.md index fe075fa..72dc001 100644 --- a/API.md +++ b/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