From 0736df57949d52d54c5ad2c792779edb2cd20985 Mon Sep 17 00:00:00 2001 From: kingpanther13 Date: Sat, 11 Jul 2026 13:41:55 -0400 Subject: [PATCH] Document Client ID Metadata Document support in the auth API Home Assistant core is gaining a Client ID Metadata Document fallback for redirect URL discovery (home-assistant/core#176286); document the JSON format and its validation requirements alongside the existing same-host and link-tag options. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01L7FvJAi5hk5vy7FvtdcZZe --- docs/auth_api.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/auth_api.md b/docs/auth_api.md index 951988d0cd2..79dfb4bb43c 100644 --- a/docs/auth_api.md +++ b/docs/auth_api.md @@ -24,6 +24,17 @@ If you require a different redirect URL (such as when building a native app), yo Home Assistant will scan the first 10kB of a website for link tags. +Alternatively, your application can serve an [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) at the client ID URL: a JSON document that lists the approved redirect URLs. This is used when no `` tags are found. For example: + +```json +{ + "client_id": "https://www.my-application.io/oauth/metadata.json", + "redirect_uris": ["https://oauth.my-application.io/hass/auth_callback"] +} +``` + +The metadata document is only accepted when the client ID URL uses `https`, the document is served directly with a `200 OK` response (redirects are not followed), its `client_id` matches the URL it was fetched from, and every `redirect_uris` entry is an absolute URI. Redirect URLs are compared by exact string match, and the 10kB scan limit applies to the document as well. Home Assistant advertises this support with `client_id_metadata_document_supported` in its OAuth authorization server metadata. + ## Authorize