From e49e2b7fbf3df9849dc174b3c1e29fec328ee60f Mon Sep 17 00:00:00 2001 From: Teemu R Date: Mon, 10 Jun 2024 21:22:55 +0200 Subject: [PATCH] Document reauth and import as reserved config flow steps (#1686) --- docs/config_entries_config_flow_handler.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md index e8214585..b4364f7a 100644 --- a/docs/config_entries_config_flow_handler.md +++ b/docs/config_entries_config_flow_handler.md @@ -63,6 +63,8 @@ There are a few step names reserved for system use: | `user` | Invoked when a user initiates a flow via the user interface or when discovered and the matching and discovery step are not defined. | | `reconfigure` | Invoked when a user initiates a flow to reconfigure an existing config entry via the user interface. | | `zeroconf` | Invoked if your integration has been discovered via Zeroconf/mDNS as specified [using `zeroconf` in the manifest](creating_integration_manifest.md#zeroconf). | +| `reauth` | Invoked if your integration indicates it [requires reauthentication, e.g., due to expired credentials](#reauthentication). | +| `import` | Reserved for migrating from YAML configuration to config entries. | ## Unique IDs @@ -275,6 +277,7 @@ class ExampleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): ## Reauthentication Gracefully handling authentication errors such as invalid, expired, or revoked tokens is needed to advance on the [Integration Quality Scale](integration_quality_scale_index.md). This example of how to add reauth to the OAuth flow created by `script.scaffold` following the pattern in [Building a Python library](api_lib_auth.md#oauth2). +If you are looking for how to trigger the reauthentication flow, see [handling expired credentials](integration_setup_failures#handling-expired-credentials). This example catches an authentication exception in config entry setup in `__init__.py` and instructs the user to visit the integrations page in order to reconfigure the integration.