Skip to content

Add long-lived access token #82

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
balloob merged 2 commits into from
Sep 11, 2018
Merged

Add long-lived access token #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a84d999
Update auth_index.md
awarecan Sep 11, 2018
a464693
Add auth/long_lived_access_token WS API
awarecan Sep 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/auth_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

```
Expand All @@ -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.
Expand Down
9 changes: 8 additions & 1 deletion docs/auth_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.