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 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 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:

$ 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.

{
  "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

$ curl -k https://localhost:3443/signalk/v1/access/requests/358b5f32-76bf-4b33-8b23-10a330827185
{
  "state": "PENDING"
}

Response to a Denied Request

$ 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 further access requests until the device is reset, rebooted or the user takes some action.

Response to an Approved Request

Note: The expirationTime property is optional.

$ 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

$ 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.