From f7a538d2d1af78fd235b038b53d4ff8ac084d0c5 Mon Sep 17 00:00:00 2001
From: Jason Stirnaman <stirnamanj@gmail.com>
Date: Thu, 3 Jul 2025 14:26:37 -0500
Subject: [PATCH] chore(v2): Explain v1-compatible auth and add a
 troubleshooting section with a negative example. Putting a bow on #4393.
 Verified that Kapa.ai knows how to authenticate to v1 endpoints in each
 version

---
 .../shared/influxdb-v2/api-guide/api_intro.md |  6 +--
 .../api-guide/influxdb-1x/_index.md           | 48 +++++++++++++++++--
 2 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/content/shared/influxdb-v2/api-guide/api_intro.md b/content/shared/influxdb-v2/api-guide/api_intro.md
index d5cdd1702..6c4719897 100644
--- a/content/shared/influxdb-v2/api-guide/api_intro.md
+++ b/content/shared/influxdb-v2/api-guide/api_intro.md
@@ -5,9 +5,9 @@ This section guides you through the most commonly used API methods.
 
 For detailed documentation on the entire API, see the [InfluxDB v2 API Reference](/influxdb/version/reference/api/#influxdb-v2-api-documentation).
 
-{{% note %}}
-If you need to use InfluxDB {{< current-version >}} with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility API](/influxdb/version/reference/api/#influxdb-v1-compatibility-api-reference-documentation).
-{{% /note %}}
+> [!Tip]
+> #### Use {{< current-version >}} API with InfluxDB 1.x clients
+> If you need to use InfluxDB {{< current-version >}} with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility guide](/influxdb/version/reference/api/influxdb-1x/).
 
 ## Bootstrap your application
 
diff --git a/content/shared/influxdb-v2/api-guide/influxdb-1x/_index.md b/content/shared/influxdb-v2/api-guide/influxdb-1x/_index.md
index fc992830d..45361a381 100644
--- a/content/shared/influxdb-v2/api-guide/influxdb-1x/_index.md
+++ b/content/shared/influxdb-v2/api-guide/influxdb-1x/_index.md
@@ -10,8 +10,13 @@ InfluxDB 1.x compatibility endpoints require all query and write requests to be
 [API token](/influxdb/version/admin/tokens/) or 1.x-compatible
 credentials.
 
-* [Authenticate with the Token scheme](#authenticate-with-the-token-scheme)
-* [Authenticate with a 1.x username and password scheme](#authenticate-with-a-username-and-password-scheme)
+> [!Important]
+> #### Authenticate with an API token or 1.x-compatible credentials
+> You can't use an InfluxDB 2.x username and password to authenticate with the InfluxDB 1.x compatibility API.
+
+- [Authenticate with the Token scheme](#authenticate-with-the-token-scheme)
+- [Authenticate with a 1.x username and password scheme](#authenticate-with-a-username-and-password-scheme)
+- [Troubleshoot authentication issues](#troubleshoot-authentication-issues)
 
 ### Authenticate with the Token scheme
 Token authentication requires the following credential:
@@ -259,7 +264,44 @@ Replace the following:
 
 {{% /show-in %}}
 
-##### InfluxQL support
+### Troubleshoot authentication issues
+
+#### Unauthorized when using the initial username and password
+
+You can't use the InfluxDB 2.x username and password to authenticate with the InfluxDB 1.x compatibility API.
+For example, given the following Docker Compose configuration: 
+
+```yaml
+# Docker compose example
+  influx2:
+    image: influxdb:2.4.0
+    volumes:
+      - ./dev/influxdb2:/var/lib/influxdb2
+    ports:
+      - "8086:8086"
+    environment:
+      DOCKER_INFLUXDB_INIT_USERNAME: dev
+      DOCKER_INFLUXDB_INIT_PASSWORD: 12345678
+      DOCKER_INFLUXDB_INIT_ORG: com.some
+      DOCKER_INFLUXDB_INIT_BUCKET: m2_dev
+      DOCKER_INFLUXDB_INIT_MODE: setup
+```
+
+The following query using the v1 `/query` endpoint and v2 initial username and password returns an `unauthorized` error:
+
+```bash
+# Using the initial username and password
+curl --get "http://localhost:8086/query" \
+    --data-urlencode "u=dev" \
+    --data-urlencode "p=12345678" \
+    --data-urlencode "db=m2_dev" \
+    --data-urlencode "q=SELECT * FROM default"
+```
+
+Instead, [authenticate with a token](#authenticate-with-the-token-scheme) or a [1.x username and password scheme](#authenticate-with-a-username-and-password-scheme).
+
+
+## InfluxQL support
 
 The compatibility API supports InfluxQL, with the following caveats: