developers.home-assistant/website/versioned_docs/version-0.73.0/auth_api.md

title	sidebar_label	id	original_id
Authentication API	API	version-0.73.0-auth_api	auth_api

This is experimental. It is not persisted and is not yet intended for production.

This page will describe the steps required to fetch an access token for a user and how to refresh it. We follow the OAuth 2 specification.

Requirements

A client needs to be created inside Home Assistant before a client can request users to authorize it or fetch a new access token. The only way currently to create a client is programmatically:

client = await hass.auth.async_get_or_create_client(
    'Example client',
    redirect_uris=['http://www.example.com/hass_callback']
)
print(client.id)

Authorize

• The authorize url should contain client_id, redirect_uri and, if available, client_secret as query parameters. Example: http://your-instance.com/auth/authorize?client_id=ABCDE&client_secret=QWERTY&redirect_uri=https%3A%2F%2Fexample.com%2Fhass_callback
• The user will navigate to this link, log into Home Assistant and authorize the client.
• Once authorized, the user will be redirected back to the passed in redirect uri with the authorization code as part of the query parameters. Example: https://example.com/hass_callback?code=12345
• This authorization code can be exchanged for tokens by sending it to the token endpoint (see next section).
• As specified in the OAuth 2 specification, it is possible to pass an optional state string to the authorize url using the state query parameter. This string will be added as query parameter to the redirect url.

Token

The token endpoint returns tokens given valid grants. This grant is either an authorization code retrieved from the authorize endpoint or a refresh token.

All interactions with this endpoint need to be HTTP POST requests to http://your-instance.com/auth/token with the request body encoded in application/x-www-form-urlencoded.

Authorization code

Use the grant type authorization_code to retrieve the tokens after a user has successfully finished the authorize step. The request body is:

grant_type=authorization_code&code=12345

The return response will be an access and refresh token:

{
    "access_token": "ABCDEFGH",
    "expires_in": 1800,
    "refresh_token": "IJKLMNOPQRST",
    "token_type": "Bearer"
}

Refresh token

Use the grant type refresh_token to retrieve an access token using a refresh token. The request body is:

grant_type=refresh_token&refresh_token=QWERTY

The return response will be an access token:

{
    "access_token": "ABCDEFGH",
    "expires_in": 1800,
    "token_type": "Bearer"
}

Making authenticated requests

Once you have an access token, you can make authenticated requests to the Home Assistant APIs.

For the websocket connection, pass the access token in the authentication message.

For HTTP requests, pass the token type and access token as the authorization header:

Authorization: Bearer ABCDEFGH

If the access token is no longer valid, you will get a response with HTTP status code 401 unauthorized. This means that you will need to refresh the token. If the refresh token doesn't work, the tokens are no longer valid and the client should ask the user to authorize again.