jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-22 00:36:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add long-lived access token (#82)

Browse Source 
* Update auth_index.md

* Add auth/long_lived_access_token WS API
This commit is contained in:
Jason Hu 2018-09-11 08:36:06 -07:00 committed by Paulus Schoutsen
parent 4ea6246370
commit cfa016e33a
2 changed files with 33 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/auth_api.md
View File

@ -128,6 +128,8 @@ An HTTP status code of 400 will be returned if an invalid request has been issue
### Revoking a refresh token
> client_id is not need for revoke refresh token
The token endpoint is also capable of revoking a refresh token. Revoking a refresh token will immedeatly revoke the refresh token and all access tokens that it has ever granted. To revoke a refresh token, make the following request:
```
@ -137,6 +139,29 @@ action=revoke
The request will always respond with an empty body and HTTP status 200, regardless if the request was successful.
## Long-lived access token
A long-lived access token is usally used for 3rd party API calls and webhook-ish integrations. To generate a long-lived access token, an active websocket connection has to be established.
Send websocket command `auth/long_lived_access_token` will create a long-lived access token for current user. Access token will not be saved in Home Assistant. User need to record the token in secure place.
{
"id": 11,
"type": "auth/long_lived_access_token",
"client_name": "GPS Logger",
"client_icon": null,
"lifespan": 365
}
Result will be a long-lived access token:
{
"id": 11,
"type": "result",
"success": true,
"result": "ABCDEFGH"
}
## Making authenticated requests
Once you have an access token, you can make authenticated requests to the Home Assistant APIs.

9
docs/auth_index.md
View File

@ -29,10 +29,17 @@ The first user to log in to Home Assistant will be marked as the owner. This use
## Clients
Clients are applications that users use to access the Home Assistant API. Each client has a client identifier, a redirect uri and an optional client secret. The redirect uri is used to redirect the user after it has successfully authorized.
Clients are applications that users use to access the Home Assistant API. Each client has a client identifier and a redirect uri. The redirect uri is used to redirect the user after it has successfully authorized.
## Access and refresh tokens
The client will be provided with an authorization code when a user successfully authorizes with Home Assistant. This code can be used to retrieve an access and a refresh token. The access token will have a limited lifetime while refresh tokens will remain valid until a user deletes it.
The access token is used to access the Home Assistant APIs. The refresh token is used to retrieve a new valid access token.
### Refresh token types
Refresh token has 3 different types:
- *Normal*: is generated by a success log in request, and will be sent to user and possessed by user.
- *System*: can only be generated by system user.
- *Long-lived Access Token*: such refresh token is generated by user, but will not delivery to user, however the access token generated by this refresh token will send to user.