Merge pull request #6188 from influxdata/jstirnaman/issue4393

Clarify authorization for v1-compatibility endpoints in v2

Author: jstirnaman

content/shared/influxdb-v2/api-guide/api_intro.md

@@ -5,15 +5,15 @@ 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 InfluxDB 1.x API clients with {{< current-version >}}
+> 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
 
 With most API requests, you'll need to provide a minimum of your InfluxDB URL and Authorization Token (API Token).
 
-[Install InfluxDB OSS v2.x](/influxdb/version/install/) or upgrade to
+[Install InfluxDB OSS v2.x](/influxdb/v2/install/) or upgrade to
 an [InfluxDB Cloud account](/influxdb/cloud/sign-up).
 
 ### Authentication

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:
 

content/shared/influxdb-v2/monitor-alert/templates/monitor.md

@@ -17,7 +17,7 @@ Do the following:
 Before you begin, make sure you have access to the following:
 
 - InfluxDB Cloud account ([sign up for free here](https://cloud2.influxdata.com/signup))
-- Command line access to a machine [running InfluxDB OSS 2.x](/influxdb/version/install/) and permissions to install Telegraf on this machine
+- Command line access to a machine [running InfluxDB OSS 2.x](/influxdb/v2/install/) and permissions to install Telegraf on this machine
 - Internet connectivity from the machine running InfluxDB OSS 2.x and Telegraf to InfluxDB Cloud
 - Sufficient resource availability to install the template (InfluxDB Cloud Free
   Plan accounts include [resource limits](/influxdb/cloud/account-management/pricing-plans/#resource-limits/influxdb/cloud/account-management/pricing-plans/#resource-limits))
@@ -53,9 +53,9 @@ InfluxDB OSS metrics to an InfluxDB endpoint and a dashboard that visualizes the
 By default, InfluxDB OSS 2.x has a `/metrics` endpoint available, which exports 
 internal InfluxDB metrics in [Prometheus format](https://prometheus.io/docs/concepts/data_model/).
 
-1. Ensure the `/metrics` endpoint is [enabled](/influxdb/version/reference/config-options/#metrics-disabled).
+1. Ensure the `/metrics` endpoint is [enabled](/influxdb/v2/reference/config-options/#metrics-disabled).
    If you've changed the default settings to disable the `/metrics` endpoint,
-   [re-enable these settings](/influxdb/version/reference/config-options/#metrics-disabled).
+   [re-enable these settings](/influxdb/v2/reference/config-options/#metrics-disabled).
 2. Navigate to the `/metrics` endpoint of your InfluxDB OSS instance to view the InfluxDB OSS system metrics in your browser: 
 
 ## Set up Telegraf

content/shared/influxdb-v2/write-data/migrate-data/migrate-cloud-to-oss.md

@@ -22,7 +22,7 @@ each batch to an InfluxDB OSS bucket.
 
 ## Set up the migration
 
-1.  [Install and set up InfluxDB OSS](/influxdb/version/install/).
+1.  [Install and set up InfluxDB OSS](/influxdb/v2/install/).
 
 2.  **In InfluxDB Cloud**, [create an API token](/influxdb/cloud/admin/tokens/create-token/)
         with **read access** to the bucket you want to migrate.

content/shared/influxdb-v2/write-data/replication/_index.md

@@ -1,5 +1,5 @@
 
-Running [InfluxDB OSS](/influxdb/version/install/) at the edge lets you collect, process, transform, and analyze high-precision data locally.
+Running [InfluxDB OSS](/influxdb/v2/install/) at the edge lets you collect, process, transform, and analyze high-precision data locally.
 **Edge Data Replication** lets you replicate data from distributed edge environments to [InfluxDB Cloud](/influxdb/cloud/sign-up/), aggregating and storing data for long-term management and analysis.
 
 {{< youtube qsj_TTpDyf4 >}}