From fb614a9f0b405c055d743381c66d6c61a3fd1363 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Wed, 24 Oct 2018 17:43:58 +0200 Subject: [PATCH] Add docs for signed path --- docs/auth_api.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/auth_api.md b/docs/auth_api.md index e2e00345..58fdd8ee 100644 --- a/docs/auth_api.md +++ b/docs/auth_api.md @@ -219,3 +219,34 @@ If the access token is no longer valid, you will get a response with HTTP status [oauth2-spec]: https://tools.ietf.org/html/rfc6749 [indieauth-spec]: https://indieauth.spec.indieweb.org/ [indieauth-clients]: https://indieauth.spec.indieweb.org/#client-identifier + +## Signed paths + +Sometimes you want a user to make a GET request to Home Assistant to download data. In this case the normal auth system won't do, as we can't link the user to an API with the auth header attached to it. In that case, a signed path can help. + +A signed path is a normal path on our server, like `/api/states`, but with an attached secure authentication signature. The user is able to navigate to this path and will be authorised as the access token that created the signed path. Signed paths can be created via the websocket connection and are meant to be shortlived. The default expiration is 30 seconds. + +To get a signed path, send the following command: + +```js +{ + "type": "auth/sign_path", + "path": "/api/states", + // optional, expiration time in seconds. Defaults to 30 seconds + "expires": 20 +} +``` + +The response will contain the signed path: + +```js +{ + "path": "/api/states?authSig=ABCDEFGH" +} +``` + +Some things to note about a signed path: + + - If the refresh token is deleted, the signed url is no longer valid. + - If the user is deleted, the signed url is no longer valid (because the refresh token will be deleted). + - If Home Assistant is restarted, the signed url is no longer valid.