feature: define process for devices to request access to a server (#505)

gitbook-docs/SUMMARY.md

@@ -23,3 +23,4 @@
 * [Appendix B: Keys Reference (Others)](otherBranches.md)
 * [Appendix C: Changelog](changelog.md)
 * [Appendix D: Versioning](versioning.md)
+* [Appendix E: Access Requests](access_requests.md)

gitbook-docs/access_requests.md

@@ -0,0 +1,103 @@
+# Access Requests
+
+When a device needs to gain access to a secured Signal K server, it can use __Access Requests__ to request and be
+granted access to the server.
+
+See [Request/Response](request_response.md) for more information on request/response semantics.
+
+A device could be a display or for example an engine sensor or a temperature sensor.
+
+## Definitions
+
+* `clientId` is a string that uniquely identifies a device. It must be a [v4 UUID](https://tools.ietf.org/html/rfc4122.html#section-4.4)  The client should use the same
+  value for all its requests.
+* `requestId` is a string generated by the server in response to an access request and used by the client to correlate
+  the request with the results. The client should not rely on the format or contents of this string.
+
+## Device Requests
+
+The device will send a REST request to the server:
+
+```sh
+$ curl -k \
+    --header "Content-Type: application/json" \
+    --request POST \
+    --data '{"clientId":"1234-45653-343453","description":"My Awesome Humidity Sensor"}' \
+    https://localhost:3443/signalk/v1/access/requests
+```
+
+If the server does not support access requests it must return HTTP status code 501 Not Implemented.
+
+For a successfully received access request the server must return an HTTP status code 202 and a JSON response with an
+href to check the status and get the response.
+
+```json
+{
+  "state": "PENDING",
+  "href": "/signalk/v1/access/requests/358b5f32-76bf-4b33-8b23-10a330827185"
+}
+```
+
+The server should then provide a process for an administrator to review and approve or deny the request.
+
+In the meantime, a device should poll the server using the `requestId` in the response above to see if it has been
+granted access and get the token.
+
+### Response to a Pending Request
+
+```sh
+$ curl -k https://localhost:3443/signalk/v1/access/requests/358b5f32-76bf-4b33-8b23-10a330827185
+{
+  "state": "PENDING"
+}
+```
+
+### Response to a Denied Request
+
+```sh
+$ curl -k https://localhost:3443/signalk/v1/access/requests/358b5f32-76bf-4b33-8b23-10a330827185
+{
+  "state": "COMPLETED",
+  "statusCode": 200,
+  "accessRequest": {
+    "permission": "DENIED"
+  }
+}
+```
+
+WHen a device gets a denied response, it should refrain from sending furthing access frequests until the device is reset, rebooted or the user takes some action.
+
+### Response to an Approved Request
+
+_Note:_ The `expirationTime` property is optional.
+
+```sh
+$ curl -k https://localhost:3443/signalk/v1/access/requests/358b5f32-76bf-4b33-8b23-10a330827185
+{
+  "state": "COMPLETED",
+  "statusCode": 200,
+  "accessRequest": {
+    "permission": "APPROVED",
+    "token": "eyJhbGciOiJIUzI1NiIs...BAP8bt3tNBT1WiIttm3qM",
+    "expirationTime": "2018-09-20T16:51:31.350Z"
+  }
+}
+```
+
+### Response Indicating an Error With the Request
+
+```sh
+$ curl -k https://localhost:3443/signalk/v1/access/requests/358b5f32-76bf-4b33-8b23-10a330827185
+{
+  "state": "COMPLETED",
+  "statusCode": 400,
+  "message": "A device with clientId '1234-45653-343453' has already requested access"
+}
+```
+
+### After Access Approval
+
+On approval, the device would save the token in a secure way and use it when sending or requesting data. 
+
+At some point in the future the provided token could expire, access to the server could be revoked or the server could be replaced. In all cases the server will respond to requests with a 403 status code. The device should then submit a new request for access and follow the process defined above.
+