Storing secrets

The configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file is a plain-text file, thus it is readable by anyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration.

By using !secret you can remove any private information from your configuration files. This separation can also help you to keep easier track of your passwords and API keys, as they are all stored at one place and no longer spread across the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file or even multiple YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the configuration.yaml or automations.yaml files. [Learn more] files if you split up your configuration.

Using secrets.yaml

The workflow for moving private information to secrets.yaml is very similar to the splitting of the configuration. Create a secrets.yaml file in your Home Assistant configuration directory.

The entries for password and API keys in the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file usually looks like the example below.

rest:
  - authentication: basic
    username: "admin"
    password: "YOUR_PASSWORD"
    ...

Those entries need to be replaced with !secret and an identifier.

rest:
  - authentication: basic
    username: "admin"
    password: !secret rest_password
    ...

The secrets.yaml file contains the corresponding password assigned to the identifier.

rest_password: "YOUR_PASSWORD"

Debugging secrets

When you start splitting your configuration into multiple files, you might end up with configuration in sub folders. Secrets will be resolved in this order:

• A secrets.yaml located in the same folder as the YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the configuration.yaml or automations.yaml files. [Learn more] file referencing the secret,
• next, parent folders will be searched for a secrets.yaml file with the secret, stopping at the folder with the main configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more].

To see where secrets are being loaded from, you can add an option to your secrets.yaml file.

Print where secrets are retrieved from to the Home Assistant log by adding the following to secrets.yaml:

logger: debug

This will not print the actual secret’s value to the log.

Secrets in automations and scripts

Using secrets is not supported in the Home Assistant UI YAML editor for automations and scripts. If !secret is used in automations.yaml or scripts.yaml, you will not be able to edit or view any YAML automations or scripts in the UI.

You can however split automations or scripts using secrets into a separate yaml file, as described in splitting configuration. These will be read-only in the frontend, and allow the rest of your automations to still be editable normally.

Example configuration.yaml:

# The main automations editable in the UI
automation ui: !include automations.yaml

# These automations may contain secrets, and will be read-only in the UI
automation secret: !include automations-secret.yaml