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-15 05:16:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Websocket API to use access token

Browse Source
This commit is contained in:
Paulus Schoutsen 2018-09-05 21:50:46 +02:00 committed by GitHub
parent f386f1e446
commit 5b0b1279be
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 13 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/external_api_websocket.md
View File

@ -2,13 +2,13 @@
title: "WebSocket API" title: "WebSocket API"
--- ---
Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSocket. Implementations in different languages: Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSockets. Implementations in different languages:
- [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend - [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend
- [Python](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py) - CLI client using [`asyncws`](https://async-websockets.readthedocs.io/en/latest/) - [Python](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py) - CLI client using [`asyncws`](https://async-websockets.readthedocs.io/en/latest/)
- [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser - [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser
Connect your websocket implementation to `ws://localhost:8123/api/websocket`. Connect your websocket implementation to `ws://localhost:8123/api/websocket`. You will need a valid access token.
If you are not using the [`frontend`](https://www.home-assistant.io/components/frontend/) in your setup then you need to add the [`websocket_api` component](https://www.home-assistant.io/components/websocket_api/) to your `configuration.yaml` file to use the WebSocket API. If you are not using the [`frontend`](https://www.home-assistant.io/components/frontend/) in your setup then you need to add the [`websocket_api` component](https://www.home-assistant.io/components/websocket_api/) to your `configuration.yaml` file to use the WebSocket API.
@ -16,7 +16,6 @@ If you are not using the [`frontend`](https://www.home-assistant.io/components/f
1. Client connects. 1. Client connects.
1. Authentication phase starts. 1. Authentication phase starts.
- If no further authentication necessary for the user: go to 3.
- Server sends `auth_required` message. - Server sends `auth_required` message.
- Client sends `auth` message. - Client sends `auth` message.
- If `auth` message correct: go to 3. - If `auth` message correct: go to 3.
@ -39,13 +38,13 @@ Example of an auth message:
```json ```json
{ {
"type": "auth", "type": "auth",
"api_password": "supersecret" "access_token": "ABCDEFGHIJKLMNOPQ"
} }
``` ```
```json ```json
{ {
"id" 5, "id": 5,
"type":"event", "type":"event",
"event":{ "event":{
"data":{}, "data":{},
@ -76,16 +75,7 @@ If authentication is necessary, the server sends out `auth_required`.
} }
``` ```
This means that the next message from the client should be an auth message. You can authorize with either an API password (legacy auth) or an access token. This means that the next message from the client should be an auth message. You can authorize with an access token.
```json
{
"type": "auth",
"api_password": "supersecret"
}
```
or
```json ```json
{ {
@ -94,6 +84,14 @@ or
} }
``` ```
For now, we also support authentication with an API password (legacy auth).
```json
{
"type": "auth",
"api_password": "supersecret"
}
```
If the client supplies valid authentication, the authentication phase will complete by the server sending the `auth_ok` message: If the client supplies valid authentication, the authentication phase will complete by the server sending the `auth_ok` message: