From 8ca724fdb686f34e1182c0af56724dfd7601cdd6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aur=C3=A9lien=20Sibiril?=
 <81782+aureliensibiril@users.noreply.github.com>
Date: Thu, 4 Jun 2026 19:09:04 +0200
Subject: [PATCH] Document why OAuth uses two token-URL closures
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BuildTokenURLForDomain and BuildTokenURLForSite cannot be merged: a
provider's signed-state Site (e.g. Datadog's region key) is not always the
string its token host needs (the API domain). Spell that out at the switch
so the split is not mistaken for accidental duplication.

Signed-off-by: Aurélien Sibiril <81782+aureliensibiril@users.noreply.github.com>
---
 pkg/connector/oauth2.go | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/pkg/connector/oauth2.go b/pkg/connector/oauth2.go
index d8e402adf..9acd6c47b 100644
--- a/pkg/connector/oauth2.go
+++ b/pkg/connector/oauth2.go
@@ -391,6 +391,14 @@ func (c *OAuth2Connector) CompleteWithState(ctx context.Context, r *http.Request
 		codeVerifier = derivePKCEVerifier(c.stateSalt(), payload.Data.PKCENonce)
 	}
 
+	// Multi-site providers build the token host from a per-customer value that
+	// reaches the callback by one of two mutually exclusive routes (Register
+	// rejects setting both): a host the provider echoes back as a query param
+	// (BuildTokenURLForDomain — Datadog's ?domain=), or the site carried in the
+	// signed state when the provider echoes nothing (BuildTokenURLForSite —
+	// Zendesk's subdomain). They cannot share one closure: a provider's state
+	// Site (e.g. Datadog's region key "US3") is not necessarily the string its
+	// token host needs (Datadog's API domain "us3.datadoghq.com").
 	tokenURL := c.TokenURL
 	switch {
 	case c.BuildTokenURLForDomain != nil: