home-assistant/core · error · ConfigEntryAuthFailed

invalid_api_key

invalid_api_key

Error message

Invalid API key. Please verify your API key and try to reauthenticate.

What it means

ConfigEntryAuthFailed raised during Aqvify coordinator setup (translation_key 'invalid_api_key') when api_client.async_get_account_id() raises AqvifyAuthException. It tells Home Assistant the stored API key is no longer accepted, so the config entry is put into setup-error/reauth state instead of retrying uselessly.

Source

Thrown at homeassistant/components/aqvify/coordinator.py:76

        """Initialize the Aqvify data update coordinator."""
        super().__init__(
            hass,
            logger=_LOGGER,
            name=f"{DOMAIN} main",
            update_interval=UPDATE_INTERVAL,
            config_entry=entry,
        )

        self.api_client = api_client
        self.previous_devices: set[str] = set()

    @override
    async def _async_setup(self) -> None:
        """Set up the coordinator."""
        try:
            await self.api_client.async_get_account_id()
        except AqvifyAuthException:
            raise ConfigEntryAuthFailed(
                translation_domain=DOMAIN,
                translation_key="invalid_api_key",
            ) from None
        except ClientResponseError as err:
            raise ConfigEntryNotReady(
                translation_domain=DOMAIN,
                translation_key="api_error",
                translation_placeholders={
                    "entry": self.config_entry.title,
                },
            ) from err
        except TimeoutError as err:
            raise ConfigEntryNotReady(
                translation_domain=DOMAIN,
                translation_key="api_timeout",
                translation_placeholders={
                    "entry": self.config_entry.title,
                },

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Open the Aqvify config entry in HA and start the re-authentication flow, pasting the current API key from your Aqvify account.
Verify the key by calling the Aqvify API directly (e.g. GET /accounts/me with the key) outside HA.
Ensure the key comes from the same account that owns the devices you expect.

Example fix

# verify the key before relying on HA setup
curl -H "Authorization: Bearer $AQTIFY_API_KEY" https://api.aqvify.com/api/v1/accounts/me

Defensive patterns

Strategy: try-catch

Validate before calling

import aiohttp

async def key_works(session: aiohttp.ClientSession, api_key: str) -> bool:
    async with session.get(
        "https://api.aqvify.com/api/v1/accounts/me",
        headers={"Authorization": f"Bearer {api_key}"},
    ) as resp:
        return resp.status == 200

Try / catch

from aqvify_client.exceptions import AqvifyAuthException

try:
    account_id = await api_client.async_get_account_id()
except AqvifyAuthException:
    # prompt user for a new API key; run reauth flow
raise

Prevention

Paste API keys via secrets and double-check for whitespace/truncation.
Test the key against the Aqvify API before configuring the integration.
When regenerating a key in the portal, immediately re-authenticate the HA entry.

When it happens

Trigger: During coordinator _async_setup, the first authenticated call async_get_account_id() returns an auth failure (401/403) because the API key in entry.data is wrong, revoked, or belongs to another account.

Common situations: Typo in the API key during config flow; key regenerated in the Aqvify portal which invalidates the old one; key copied from a different account; REST client caching an entry with an old key after re-configuration.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/2f33b8509e48404e. Report an issue: GitHub.