diff --git a/api-docs/influxdb/cloud/v2/ref.yml b/api-docs/influxdb/cloud/v2/ref.yml index 72bee2d657..365e6d7db0 100644 --- a/api-docs/influxdb/cloud/v2/ref.yml +++ b/api-docs/influxdb/cloud/v2/ref.yml @@ -13731,7 +13731,7 @@ components: Default is [`RFC3339` date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. - #### Example formatted date/time values + ### Example formatted date/time values | Format | Value | |:------------|:----------------------------| diff --git a/api-docs/influxdb/v2/v2/ref.yml b/api-docs/influxdb/v2/v2/ref.yml index ffc8263388..778aceaccc 100644 --- a/api-docs/influxdb/v2/v2/ref.yml +++ b/api-docs/influxdb/v2/v2/ref.yml @@ -13270,7 +13270,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LineProtocolError' - description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. + description: Line protocol is poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. '401': content: application/json: @@ -13282,7 +13282,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: No token was sent and they are required. + description: The request didn't provide an authorization token. '413': content: application/json: @@ -13293,8 +13293,8 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Error' - description: The request was well-formed, but some or all the points were rejected due to semantic errors--for example, schema conflicts or retention policy violations. Error message contains details for one or more rejected points. + $ref: '#/components/schemas/Error' + description: The request was well-formed, but some points were rejected due to semantic errors--for example, schema conflicts or retention policy violations. Error message contains details for one or more rejected points. '429': description: Token is temporarily over quota. The Retry-After header describes when to try the write again. headers: @@ -14857,7 +14857,7 @@ components: Default is [`RFC3339` date/time format](/influxdb/v2/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. - #### Example formatted date/time values + ### Example formatted date/time values | Format | Value | |:------------|:----------------------------| diff --git a/api-docs/influxdb3/cloud-dedicated/v2/ref.yml b/api-docs/influxdb3/cloud-dedicated/v2/ref.yml index c4b6454644..b638df94f1 100644 --- a/api-docs/influxdb3/cloud-dedicated/v2/ref.yml +++ b/api-docs/influxdb3/cloud-dedicated/v2/ref.yml @@ -63,12 +63,14 @@ tags: name: API compatibility x-traitTag: true - description: | - Use one of the following schemes to authenticate to the InfluxDB API: - - - [Bearer authentication](#section/Authentication/BearerAuthentication) - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) - - [Querystring authentication](#section/Authentication/QuerystringAuthentication) + Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API: + + | Authentication scheme | Works with | + |:-------------------|:-----------| + | [Bearer authentication](#section/Authentication/BearerAuthentication) | All endpoints | + | [Token authentication](#section/Authentication/TokenAuthentication) | v1, v2 endpoints | + | [Basic authentication](#section/Authentication/BasicAuthentication) | v1 endpoints | + | [Querystring authentication](#section/Authentication/QuerystringAuthentication) | v1 endpoints | name: Authentication x-traitTag: true @@ -1097,7 +1099,7 @@ components: Default is [`RFC3339` date/time format](/influxdb3/cloud-dedicated/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. - #### Example formatted date/time values + ### Example formatted date/time values | Format | Value | |:------------|:----------------------------| @@ -1978,61 +1980,45 @@ components: type: string securitySchemes: BasicAuthentication: + type: http + scheme: basic description: | - ### Basic authentication scheme - - Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` and `/query` requests. - When authenticating requests, InfluxDB 3 Cloud Dedicated checks that the `password` part of the decoded credential is an authorized [database token](/influxdb3/cloud-dedicated/admin/tokens/). - InfluxDB 3 Cloud Dedicated ignores the `username` part of the decoded credential. - - ### Syntax + Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests. - ```http - Authorization: Basic - ``` - - Replace the following: + Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3. - - **`[USERNAME]`**: an optional string value (ignored by InfluxDB 3 Cloud Dedicated). - - **`DATABASE_TOKEN`**: a [database token](/influxdb3/cloud-dedicated/admin/tokens/). - - Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. + When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token + and ignores the `username` part of the decoded credential. ### Example - The following example shows how to use cURL with the `Basic` authentication scheme and a [database token](/influxdb3/cloud-dedicated/admin/tokens/): - - ```sh - ####################################### - # Use Basic authentication with a database token - # to query the InfluxDB v1 HTTP API - ####################################### - # Use the --user option with `--user username:DATABASE_TOKEN` syntax - ####################################### - - curl --get "http://cluster-id.a.influxdb.io/query" \ + ```bash + curl "https://cluster-id.a.influxdb.io/write?db=DATABASE_NAME&precision=s" \ --user "":"DATABASE_TOKEN" \ - --data-urlencode "db=DATABASE_NAME" \ - --data-urlencode "q=SELECT * FROM MEASUREMENT" + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: - **`DATABASE_NAME`**: your InfluxDB 3 Cloud Dedicated database - - **`DATABASE_TOKEN`**: a [database token](/influxdb3/cloud-dedicated/admin/tokens/) with sufficient permissions to the database - scheme: basic - type: http + - **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/) QuerystringAuthentication: type: apiKey in: query name: u=&p= description: | - Use the Querystring authentication - scheme with InfluxDB 1.x API parameters to provide credentials through the query string. + Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests. - ### Query string authentication + Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints. - In the URL, pass the `p` query parameter to authenticate `/write` and `/query` requests. - When authenticating requests, InfluxDB 3 Cloud Dedicated checks that `p` (_password_) is an authorized database token and ignores the `u` (_username_) parameter. + When authenticating requests, InfluxDB 3 checks that the `p` (_password_) query parameter is an authorized token + and ignores the `u` (_username_) query parameter. ### Syntax @@ -2041,11 +2027,20 @@ components: https://cluster-id.a.influxdb.io/write/?[u=any]&p=DATABASE_TOKEN ``` - ### Example + ### Examples + + ```bash + curl "https://cluster-id.a.influxdb.io/write?db=DATABASE_NAME&precision=s&p=DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' + ``` - The following example shows how to use cURL with query string authentication and a [database token](/influxdb3/cloud-dedicated/admin/tokens/). + Replace the following: - ```sh + - **`DATABASE_NAME`**: your InfluxDB 3 Cloud Dedicated database + - **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database + + ```bash ####################################### # Use an InfluxDB 1.x compatible username and password # to query the InfluxDB v1 HTTP API @@ -2062,16 +2057,23 @@ components: Replace the following: - - **`DATABASE_NAME`**: your InfluxDB 3 Cloud Dedicated database - - **`DATABASE_TOKEN`**: a [database token](/influxdb3/cloud-dedicated/admin/tokens/) with sufficient permissions to the database + - **`DATABASE_NAME`**: the database to query + - **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/) BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: | + Use the OAuth Bearer authentication - scheme to authenticate to the InfluxDB API. + scheme to provide an authorization token to InfluxDB 3. + Bearer authentication works with all endpoints. In your API requests, send an `Authorization` header. For the header value, provide the word `Bearer` followed by a space and a database token. @@ -2080,29 +2082,20 @@ components: ### Syntax ```http - Authorization: Bearer INFLUX_TOKEN + Authorization: Bearer DATABASE_TOKEN ``` ### Example - ```sh - ######################################################## - # Use the Bearer token authentication scheme with /api/v2/write - # to write data. - ######################################################## - - curl --request post "https://cluster-id.a.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \ - --header "Authorization: Bearer DATABASE_TOKEN" \ - --data-binary 'home,room=kitchen temp=72 1463683075' + ```bash + curl https://cluster-id.a.influxdb.io/api/v3/query_influxql \ + --header "Authorization: Bearer DATABASE_TOKEN" ``` - - For examples and more information, see the following: - - [Authenticate API requests](/influxdb3/cloud-dedicated/primers/api/v2/#authenticate-api-requests) - - [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/) TokenAuthentication: description: | - Use the Token authentication - scheme to authenticate to the InfluxDB API. + Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3. + + The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3. In your API requests, send an `Authorization` header. For the header value, provide the word `Token` followed by a space and a database token. @@ -2111,7 +2104,7 @@ components: ### Syntax ```http - Authorization: Token INFLUX_API_TOKEN + Authorization: Token DATABASE_TOKEN ``` ### Example @@ -2129,7 +2122,6 @@ components: ### Related guides - - [Authenticate API requests](/influxdb3/cloud-dedicated/primers/api/v2/#authenticate-api-requests) - [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/) in: header name: Authorization diff --git a/api-docs/influxdb3/cloud-serverless/v2/ref.yml b/api-docs/influxdb3/cloud-serverless/v2/ref.yml index 6b57c22c8c..3b8ac502e0 100644 --- a/api-docs/influxdb3/cloud-serverless/v2/ref.yml +++ b/api-docs/influxdb3/cloud-serverless/v2/ref.yml @@ -9414,7 +9414,7 @@ components: Default is [`RFC3339` date/time format](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. - #### Example formatted date/time values + ### Example formatted date/time values | Format | Value | |:------------|:----------------------------| diff --git a/api-docs/influxdb3/clustered/v2/ref.yml b/api-docs/influxdb3/clustered/v2/ref.yml index 09afff6d04..05507ea497 100644 --- a/api-docs/influxdb3/clustered/v2/ref.yml +++ b/api-docs/influxdb3/clustered/v2/ref.yml @@ -63,12 +63,14 @@ tags: name: API compatibility x-traitTag: true - description: | - Use one of the following schemes to authenticate to the InfluxDB API: - - - [Bearer authentication](#section/Authentication/BearerAuthentication) - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) - - [Querystring authentication](#section/Authentication/QuerystringAuthentication) + Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API: + + | Authentication scheme | Works with | + |:-------------------|:-----------| + | [Bearer authentication](#section/Authentication/BearerAuthentication) | All endpoints | + | [Token authentication](#section/Authentication/TokenAuthentication) | v1, v2 endpoints | + | [Basic authentication](#section/Authentication/BasicAuthentication) | v1 endpoints | + | [Querystring authentication](#section/Authentication/QuerystringAuthentication) | v1 endpoints | name: Authentication x-traitTag: true @@ -1074,7 +1076,7 @@ components: Default is [`RFC3339` date/time format](/influxdb3/clustered/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. - #### Example formatted date/time values + ### Example formatted date/time values | Format | Value | |:------------|:----------------------------| @@ -1955,12 +1957,15 @@ components: type: string securitySchemes: BasicAuthentication: + type: http + scheme: basic description: | - ### Basic authentication scheme + Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests. - Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` and `/query` requests. - When authenticating requests, InfluxDB 3 Clustered checks that the `password` part of the decoded credential is an authorized [database token](/influxdb3/clustered/admin/tokens/#database-tokens). - InfluxDB 3 Clustered ignores the `username` part of the decoded credential. + Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3. + + When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token + and ignores the `username` part of the decoded credential. ### Syntax @@ -1968,61 +1973,57 @@ components: Authorization: Basic ``` - Replace the following: - - - **`[USERNAME]`**: an optional string value (ignored by InfluxDB 3 Clustered). - - **`DATABASE_TOKEN`**: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens). - - Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. - ### Example - The following example shows how to use cURL with the `Basic` authentication scheme and a [database token](/influxdb3/clustered/admin/tokens/#database-tokens): - - ```sh - ####################################### - # Use Basic authentication with a database token - # to query the InfluxDB v1 HTTP API - ####################################### - # Use the --user option with `--user username:DATABASE_TOKEN` syntax - ####################################### - - curl --get "http://cluster-id.a.influxdb.io/query" \ + ```bash + curl "http://cluster-host.com/write?db=DATABASE_NAME&precision=s" \ --user "":"DATABASE_TOKEN" \ - --data-urlencode "db=DATABASE_NAME" \ - --data-urlencode "q=SELECT * FROM MEASUREMENT" + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: - **`DATABASE_NAME`**: your InfluxDB 3 Clustered database - - **`DATABASE_TOKEN`**: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the database - scheme: basic - type: http + - **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/clustered/admin/tokens/) QuerystringAuthentication: type: apiKey in: query name: u=&p= description: | - Use the Querystring authentication - scheme with InfluxDB 1.x API parameters to provide credentials through the query string. + Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests. - ### Query string authentication + Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints. - In the URL, pass the `p` query parameter to authenticate `/write` and `/query` requests. - When authenticating requests, InfluxDB 3 Clustered checks that `p` (_password_) is an authorized database token and ignores the `u` (_username_) parameter. + When authenticating requests, InfluxDB 3 checks that the `p` (_password_) query parameter is an authorized token + and ignores the `u` (_username_) query parameter. ### Syntax ```http - https://cluster-id.a.influxdb.io/query/?[u=any]&p=DATABASE_TOKEN - https://cluster-id.a.influxdb.io/write/?[u=any]&p=DATABASE_TOKEN + https://cluster-host.com/query/?[u=any]&p=DATABASE_TOKEN + https://cluster-host.com/write/?[u=any]&p=DATABASE_TOKEN ``` - ### Example + ### Examples - The following example shows how to use cURL with query string authentication and a [database token](/influxdb3/clustered/admin/tokens/#database-tokens). + ```bash + curl "http://cluster-host.com/write?db=DATABASE_NAME&precision=s&p=DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' + ``` - ```sh + Replace the following: + + - **`DATABASE_NAME`**: your InfluxDB 3 Clustered database + - **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database + + ```bash ####################################### # Use an InfluxDB 1.x compatible username and password # to query the InfluxDB v1 HTTP API @@ -2031,7 +2032,7 @@ components: # ?p=DATABASE_TOKEN ####################################### - curl --get "https://cluster-id.a.influxdb.io/query" \ + curl --get "https://cluster-host.com/query" \ --data-urlencode "p=DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" @@ -2039,16 +2040,23 @@ components: Replace the following: - - **`DATABASE_NAME`**: your InfluxDB 3 Clustered database - - **`DATABASE_TOKEN`**: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the database + - **`DATABASE_NAME`**: the database to query + - **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/clustered/admin/tokens/) BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: | + Use the OAuth Bearer authentication - scheme to authenticate to the InfluxDB API. + scheme to provide an authorization token to InfluxDB 3. + Bearer authentication works with all endpoints. In your API requests, send an `Authorization` header. For the header value, provide the word `Bearer` followed by a space and a database token. @@ -2057,29 +2065,20 @@ components: ### Syntax ```http - Authorization: Bearer INFLUX_TOKEN + Authorization: Bearer DATABASE_TOKEN ``` ### Example - ```sh - ######################################################## - # Use the Bearer token authentication scheme with /api/v2/write - # to write data. - ######################################################## - - curl --request post "https://cluster-id.a.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \ - --header "Authorization: Bearer DATABASE_TOKEN" \ - --data-binary 'home,room=kitchen temp=72 1463683075' + ```bash + curl http://cluster-host.com/api/v3/query_influxql \ + --header "Authorization: Bearer DATABASE_TOKEN" ``` - - For examples and more information, see the following: - - [Authenticate API requests](/influxdb3/clustered/primers/api/v2/#authenticate-api-requests) - - [Manage tokens](/influxdb3/clustered/admin/tokens/) TokenAuthentication: description: | - Use the Token authentication - scheme to authenticate to the InfluxDB API. + Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3. + + The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3. In your API requests, send an `Authorization` header. For the header value, provide the word `Token` followed by a space and a database token. @@ -2088,7 +2087,7 @@ components: ### Syntax ```http - Authorization: Token INFLUX_API_TOKEN + Authorization: Token DATABASE_TOKEN ``` ### Example @@ -2099,14 +2098,13 @@ components: # to write data. ######################################################## - curl --request post "https://cluster-id.a.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \ + curl --request post "https://cluster-host.com/api/v2/write?bucket=DATABASE_NAME&precision=s" \ --header "Authorization: Token DATABASE_TOKEN" \ --data-binary 'home,room=kitchen temp=72 1463683075' ``` ### Related guides - - [Authenticate API requests](/influxdb3/clustered/primers/api/v2/#authenticate-api-requests) - [Manage tokens](/influxdb3/clustered/admin/tokens/) in: header name: Authorization diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml index e15c42f9fb..3a604e4ddd 100644 --- a/api-docs/influxdb3/core/v3/ref.yml +++ b/api-docs/influxdb3/core/v3/ref.yml @@ -39,20 +39,22 @@ servers: default: localhost:8181 description: InfluxDB 3 Core URL security: - - BearerAuth: [] + - BearerAuthentication: [] + - TokenAuthentication: [] + - BasicAuthentication: [] + - QuerystringAuthentication: [] tags: - name: Authentication description: | - Authenticate to the InfluxDB 3 API using a bearer token. - - The InfluxDB 3 API uses tokens for authentication. - To authenticate, include the `Authorization` header in your request with the value `Bearer `. - The token must be a valid InfluxDB 3 admin token. - - #### Related guides - - - [Manage tokens](/influxdb3/core/admin/tokens/) - - [Authentication and authorization](/influxdb3/core/reference/internals/authentication/) + Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API: + + | Authentication scheme | Works with | + |:-------------------|:-----------| + | [Bearer authentication](#section/Authentication/BearerAuthentication) | All endpoints | + | [Token authentication](#section/Authentication/TokenAuthentication) | v1, v2 endpoints | + | [Basic authentication](#section/Authentication/BasicAuthentication) | v1 endpoints | + | [Querystring authentication](#section/Authentication/QuerystringAuthentication) | v1 endpoints | + x-traitTag: true - name: Cache data description: | @@ -215,9 +217,40 @@ paths: Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB. Use query parameters to specify options for writing data. + + #### Related + + - [Use compatibility APIs to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) parameters: - $ref: '#/components/parameters/dbWriteParam' - $ref: '#/components/parameters/compatibilityPrecisionParam' + - $ref: '#/components/parameters/v1UsernameParam' + - $ref: '#/components/parameters/v1PasswordParam' + - name: rp + in: query + required: false + schema: + type: string + description: | + Retention policy name. Honored but discouraged. InfluxDB 3 doesn't use retention policies. + - name: consistency + in: query + required: false + schema: + type: string + description: | + Write consistency level. Ignored by InfluxDB 3. Provided for compatibility with InfluxDB 1.x clients. + - name: Authorization + in: header + required: false + schema: + type: string + description: | + Authorization header for token-based authentication. + Supported schemes: + - `Bearer AUTH_TOKEN` - OAuth bearer token scheme + - `Token AUTH_TOKEN` - InfluxDB v2 token scheme + - `Basic ` - Basic authentication (username is ignored) - name: Content-Type in: header description: | @@ -290,6 +323,9 @@ paths: tags: - Compatibility endpoints - Write data + x-influxdata-guides: + - title: "Use compatibility APIs to write data" + href: "/influxdb3/core/write-data/http-api/compatibility-apis/" /api/v2/write: post: operationId: PostV2Write @@ -301,6 +337,10 @@ paths: Use this endpoint to send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB. Use query parameters to specify options for writing data. + + #### Related + + - [Use compatibility APIs to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) parameters: - name: Content-Type in: header @@ -373,6 +413,9 @@ paths: tags: - Compatibility endpoints - Write data + x-influxdata-guides: + - title: "Use compatibility APIs to write data" + href: "/influxdb3/core/write-data/http-api/compatibility-apis/" /api/v3/write_lp: post: operationId: PostWriteLP @@ -614,6 +657,10 @@ paths: This endpoint is compatible with InfluxDB 1.x client libraries and third-party integrations such as Grafana. Use query parameters to specify the database and the InfluxQL query. + + #### Related + + - [Use the InfluxDB v1 HTTP query API and InfluxQL to query data](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) parameters: - name: Accept in: header @@ -672,6 +719,26 @@ paths: in: query schema: $ref: '#/components/schemas/EpochCompatibility' + - $ref: '#/components/parameters/v1UsernameParam' + - $ref: '#/components/parameters/v1PasswordParam' + - name: rp + in: query + required: false + schema: + type: string + description: | + Retention policy name. Honored but discouraged. InfluxDB 3 doesn't use retention policies. + - name: Authorization + in: header + required: false + schema: + type: string + description: | + Authorization header for token-based authentication. + Supported schemes: + - `Bearer AUTH_TOKEN` - OAuth bearer token scheme + - `Token AUTH_TOKEN` - InfluxDB v2 token scheme + - `Basic ` - Basic authentication (username is ignored) responses: '200': description: | @@ -712,10 +779,18 @@ paths: tags: - Query data - Compatibility endpoints + x-influxdata-guides: + - title: "Use the InfluxDB v1 HTTP query API and InfluxQL to query data" + href: "/influxdb3/core/query-data/execute-queries/influxdb-v1-api/" post: operationId: PostExecuteV1Query summary: Execute InfluxQL query (v1-compatible) - description: Executes an InfluxQL query to retrieve data from the specified database. + description: | + Executes an InfluxQL query to retrieve data from the specified database. + + #### Related + + - [Use the InfluxDB v1 HTTP query API and InfluxQL to query data](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) requestBody: content: application/json: @@ -823,6 +898,9 @@ paths: tags: - Query data - Compatibility endpoints + x-influxdata-guides: + - title: "Use the InfluxDB v1 HTTP query API and InfluxQL to query data" + href: "/influxdb3/core/query-data/execute-queries/influxdb-v1-api/" /health: get: operationId: GetHealth @@ -1632,6 +1710,25 @@ components: required: true schema: $ref: '#/components/schemas/Format' + v1UsernameParam: + name: u + in: query + required: false + schema: + type: string + description: | + Username for v1 compatibility authentication. + When using Basic authentication or query string authentication, InfluxDB 3 ignores this parameter but allows any arbitrary string for compatibility with InfluxDB 1.x clients. + v1PasswordParam: + name: p + in: query + required: false + schema: + type: string + description: | + Password for v1 compatibility authentication. + For query string authentication, pass an admin token. + InfluxDB 3 checks that the `p` value is an authorized token. requestBodies: lineProtocolRequestBody: required: true @@ -2135,19 +2232,153 @@ components: schema: $ref: '#/components/schemas/ErrorMessage' securitySchemes: - BearerAuth: + BasicAuthentication: + type: http + scheme: basic + description: | + Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests. + + Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3. + + When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token + and ignores the `username` part of the decoded credential. + + ### Example + + ```bash + curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \ + --user "":"AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' + ``` + + Replace the following: + + - **`DATABASE_NAME`**: your InfluxDB 3 Core database + - **`AUTH_TOKEN`**: an admin token + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/core/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/core/admin/tokens/) + QuerystringAuthentication: + type: apiKey + in: query + name: u=&p= + description: | + Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests. + + Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints. + + When authenticating requests, InfluxDB 3 checks that the `p` (_password_) query parameter is an authorized token + and ignores the `u` (_username_) query parameter. + + ### Syntax + + ```http + http://localhost:8181/query/?[u=any]&p=DATABASE_TOKEN + http://localhost:8181/write/?[u=any]&p=DATABASE_TOKEN + ``` + + ### Examples + + ```bash + curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s&p=AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' + ``` + + Replace the following: + + - **`DATABASE_NAME`**: your InfluxDB 3 Core database + - **`AUTH_TOKEN`**: an admin token + + ```bash + ####################################### + # Use an InfluxDB 1.x compatible username and password + # to query the InfluxDB v1 HTTP API + ####################################### + # Use authentication query parameters: + # ?p=DATABASE_TOKEN + ####################################### + + curl --get "http://localhost:8181/query" \ + --data-urlencode "p=AUTH_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM MEASUREMENT" + ``` + + Replace the following: + + - **`DATABASE_NAME`**: the database to query + - **`AUTH_TOKEN`**: an [admin token](/influxdb3/core/admin/tokens/) + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/core/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/core/admin/tokens/) + BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: | - A Bearer token for authentication. - Provide the scheme and the API token in the `Authorization` header--for example: + Use the OAuth Bearer authentication + scheme to provide an authorization token to InfluxDB 3. + + Bearer authentication works with all endpoints. + + In your API requests, send an `Authorization` header. + For the header value, provide the word `Bearer` followed by a space and an admin token. + + + ### Syntax + + ```http + Authorization: Bearer AUTH_TOKEN + ``` + + ### Example ```bash curl http://localhost:8181/api/v3/query_influxql \ - --header "Authorization: Bearer API_TOKEN" + --header "Authorization: Bearer AUTH_TOKEN" + ``` + TokenAuthentication: + description: | + Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3. + + The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3. + + In your API requests, send an `Authorization` header. + For the header value, provide the word `Token` followed by a space and a database token. + The word `Token` is case-sensitive. + + ### Syntax + + ```http + Authorization: Token AUTH_TOKEN ``` + + ### Example + + ```sh + ######################################################## + # Use the Token authentication scheme with /api/v2/write + # to write data. + ######################################################## + + curl --request post "http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \ + --header "Authorization: Token AUTH_TOKEN" \ + --data-binary 'home,room=kitchen temp=72 1463683075' + ``` + + ### Related guides + + - [Manage tokens](/influxdb3/core/admin/tokens/) + in: header + name: Authorization + type: apiKey x-tagGroups: - name: Using the InfluxDB HTTP API tags: diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml index 34b2bd9617..493ff2c426 100644 --- a/api-docs/influxdb3/enterprise/v3/ref.yml +++ b/api-docs/influxdb3/enterprise/v3/ref.yml @@ -39,20 +39,22 @@ servers: default: localhost:8181 description: InfluxDB 3 Enterprise URL security: - - BearerAuth: [] + - BearerAuthentication: [] + - TokenAuthentication: [] + - BasicAuthentication: [] + - QuerystringAuthentication: [] tags: - name: Authentication description: | - Authenticate to the InfluxDB 3 API using a bearer token. - - The InfluxDB 3 API uses tokens for authentication. - To authenticate, include the `Authorization` header in your request with the value `Bearer `. - The token must be a valid InfluxDB 3 admin token or a resource token with the required permissions for the requested operation. - - #### Related guides - - - [Manage tokens](/influxdb3/enterprise/admin/tokens/) - - [Authentication and authorization](/influxdb3/enterprise/reference/internals/authentication/) + Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API: + + | Authentication scheme | Works with | + |:-------------------|:-----------| + | [Bearer authentication](#section/Authentication/BearerAuthentication) | All endpoints | + | [Token authentication](#section/Authentication/TokenAuthentication) | v1, v2 endpoints | + | [Basic authentication](#section/Authentication/BasicAuthentication) | v1 endpoints | + | [Querystring authentication](#section/Authentication/QuerystringAuthentication) | v1 endpoints | + x-traitTag: true - name: Cache data description: | @@ -215,9 +217,40 @@ paths: Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb3/enterprise/reference/syntax/line-protocol/) format to InfluxDB. Use query parameters to specify options for writing data. + + #### Related + + - [Use compatibility APIs to write data](/influxdb3/enterprise/write-data/http-api/compatibility-apis/) parameters: - $ref: '#/components/parameters/dbWriteParam' - $ref: '#/components/parameters/compatibilityPrecisionParam' + - $ref: '#/components/parameters/v1UsernameParam' + - $ref: '#/components/parameters/v1PasswordParam' + - name: rp + in: query + required: false + schema: + type: string + description: | + Retention policy name. Honored but discouraged. InfluxDB 3 doesn't use retention policies. + - name: consistency + in: query + required: false + schema: + type: string + description: | + Write consistency level. Ignored by InfluxDB 3. Provided for compatibility with InfluxDB 1.x clients. + - name: Authorization + in: header + required: false + schema: + type: string + description: | + Authorization header for token-based authentication. + Supported schemes: + - `Bearer AUTH_TOKEN` - OAuth bearer token scheme + - `Token AUTH_TOKEN` - InfluxDB v2 token scheme + - `Basic ` - Basic authentication (username is ignored) - name: Content-Type in: header description: | @@ -290,6 +323,9 @@ paths: tags: - Compatibility endpoints - Write data + x-influxdata-guides: + - title: "Use compatibility APIs to write data" + href: "/influxdb3/enterprise/write-data/http-api/compatibility-apis/" /api/v2/write: post: operationId: PostV2Write @@ -301,6 +337,10 @@ paths: Use this endpoint to send data in [line protocol](/influxdb3/enterprise/reference/syntax/line-protocol/) format to InfluxDB. Use query parameters to specify options for writing data. + + #### Related + + - [Use compatibility APIs to write data](/influxdb3/enterprise/write-data/http-api/compatibility-apis/) parameters: - name: Content-Type in: header @@ -373,6 +413,9 @@ paths: tags: - Compatibility endpoints - Write data + x-influxdata-guides: + - title: "Use compatibility APIs to write data" + href: "/influxdb3/enterprise/write-data/http-api/compatibility-apis/" /api/v3/write_lp: post: operationId: PostWriteLP @@ -614,6 +657,10 @@ paths: This endpoint is compatible with InfluxDB 1.x client libraries and third-party integrations such as Grafana. Use query parameters to specify the database and the InfluxQL query. + + #### Related + + - [Use the InfluxDB v1 HTTP query API and InfluxQL to query data](/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/) parameters: - name: Accept in: header @@ -672,6 +719,26 @@ paths: in: query schema: $ref: '#/components/schemas/EpochCompatibility' + - $ref: '#/components/parameters/v1UsernameParam' + - $ref: '#/components/parameters/v1PasswordParam' + - name: rp + in: query + required: false + schema: + type: string + description: | + Retention policy name. Honored but discouraged. InfluxDB 3 doesn't use retention policies. + - name: Authorization + in: header + required: false + schema: + type: string + description: | + Authorization header for token-based authentication. + Supported schemes: + - `Bearer AUTH_TOKEN` - OAuth bearer token scheme + - `Token AUTH_TOKEN` - InfluxDB v2 token scheme + - `Basic ` - Basic authentication (username is ignored) responses: '200': description: | @@ -712,10 +779,18 @@ paths: tags: - Query data - Compatibility endpoints + x-influxdata-guides: + - title: "Use the InfluxDB v1 HTTP query API and InfluxQL to query data" + href: "/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/" post: operationId: PostExecuteV1Query summary: Execute InfluxQL query (v1-compatible) - description: Executes an InfluxQL query to retrieve data from the specified database. + description: | + Executes an InfluxQL query to retrieve data from the specified database. + + #### Related + + - [Use the InfluxDB v1 HTTP query API and InfluxQL to query data](/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/) requestBody: content: application/json: @@ -823,6 +898,9 @@ paths: tags: - Query data - Compatibility endpoints + x-influxdata-guides: + - title: "Use the InfluxDB v1 HTTP query API and InfluxQL to query data" + href: "/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/" /health: get: operationId: GetHealth @@ -1726,6 +1804,25 @@ components: required: true schema: $ref: '#/components/schemas/Format' + v1UsernameParam: + name: u + in: query + required: false + schema: + type: string + description: | + Username for v1 compatibility authentication. + When using Basic authentication or query string authentication, InfluxDB 3 ignores this parameter but allows any arbitrary string for compatibility with InfluxDB 1.x clients. + v1PasswordParam: + name: p + in: query + required: false + schema: + type: string + description: | + Password for v1 compatibility authentication. + For query string authentication, pass a database token with write permissions as this parameter. + InfluxDB 3 checks that the `p` value is an authorized token. requestBodies: lineProtocolRequestBody: required: true @@ -2282,19 +2379,158 @@ components: schema: $ref: '#/components/schemas/ErrorMessage' securitySchemes: - BearerAuth: + BasicAuthentication: + type: http + scheme: basic + description: | + Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests. + + Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3. + + When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token + and ignores the `username` part of the decoded credential. + + ### Syntax + + ```http + Authorization: Basic + ``` + + ### Example + + ```bash + curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \ + --user "":"AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' + ``` + + Replace the following: + + - **`DATABASE_NAME`**: your InfluxDB 3 Enterprise database + - **`AUTH_TOKEN`**: an admin token or database token authorized for the database + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/enterprise/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/enterprise/admin/tokens/) + QuerystringAuthentication: + type: apiKey + in: query + name: u=&p= + description: | + Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests. + + Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints. + + When authenticating requests, InfluxDB 3 checks that the `p` (_password_) query parameter is an authorized token + and ignores the `u` (_username_) query parameter. + + ### Syntax + + ```http + https://localhost:8181/query/?[u=any]&p=AUTH_TOKEN + https://localhost:8181/write/?[u=any]&p=AUTH_TOKEN + ``` + + ### Examples + + ```bash + curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s&p=AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' + ``` + + Replace the following: + + - **`DATABASE_NAME`**: your InfluxDB 3 Enterprise database + - **`AUTH_TOKEN`**: an admin token or database token authorized for the database + + ```bash + ####################################### + # Use an InfluxDB 1.x compatible username and password + # to query the InfluxDB v1 HTTP API + ####################################### + # Use authentication query parameters: + # ?p=AUTH_TOKEN + ####################################### + + curl --get "http://localhost:8181/query" \ + --data-urlencode "p=AUTH_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM MEASUREMENT" + ``` + + Replace the following: + + - **`DATABASE_NAME`**: the database to query + - **`AUTH_TOKEN`**: a database token with sufficient permissions to the database + + #### Related guides + + - [Authenticate v1 API requests](/influxdb3/enterprise/guides/api-compatibility/v1/) + - [Manage tokens](/influxdb3/enterprise/admin/tokens/) + BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: | - A Bearer token for authentication. - Provide the scheme and the API token in the `Authorization` header--for example: + Use the OAuth Bearer authentication + scheme to provide an authorization token to InfluxDB 3. + + Bearer authentication works with all endpoints. + + In your API requests, send an `Authorization` header. + For the header value, provide the word `Bearer` followed by a space and a database token. + + ### Syntax + + ```http + Authorization: Bearer AUTH_TOKEN + ``` + + ### Example ```bash curl http://localhost:8181/api/v3/query_influxql \ - --header "Authorization: Bearer API_TOKEN" + --header "Authorization: Bearer AUTH_TOKEN" ``` + TokenAuthentication: + description: | + Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3. + + The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3. + + In your API requests, send an `Authorization` header. + For the header value, provide the word `Token` followed by a space and a database token. + The word `Token` is case-sensitive. + + ### Syntax + + ```http + Authorization: Token AUTH_TOKEN + ``` + + ### Example + + ```sh + ######################################################## + # Use the Token authentication scheme with /api/v2/write + # to write data. + ######################################################## + + curl --request post "http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \ + --header "Authorization: Token AUTH_TOKEN" \ + --data-binary 'home,room=kitchen temp=72 1463683075' + ``` + + ### Related guides + + - [Manage tokens](/influxdb3/enterprise/admin/tokens/) + in: header + name: Authorization + type: apiKey x-tagGroups: - name: Using the InfluxDB HTTP API tags: diff --git a/compose.yaml b/compose.yaml index fd0e5ea07a..ea11e03cb4 100644 --- a/compose.yaml +++ b/compose.yaml @@ -22,7 +22,7 @@ services: RUN apk add --no-cache curl openssl command: hugo server --bind 0.0.0.0 healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:1313/influxdb/cloud-dedicated/"] + test: ["CMD", "curl", "-f", "http://localhost:1313/influxdb3/cloud-dedicated/"] interval: 1m timeout: 10s retries: 2 @@ -106,9 +106,9 @@ services: command: # In the command, pass file paths to test. # The container preprocesses the files for testing and runs the tests. - - content/influxdb/cloud-dedicated/**/*.md + - content/influxdb3/cloud-dedicated/**/*.md environment: - - CONTENT_PATH=content/influxdb/cloud-dedicated + - CONTENT_PATH=content/influxdb3/cloud-dedicated profiles: - test - v3 @@ -125,12 +125,12 @@ services: source: ./test/shared target: /shared - type: bind - source: ./content/influxdb/cloud-dedicated/.env.test + source: ./content/influxdb3/cloud-dedicated/.env.test target: /app/.env.test read_only: true - # The following mount assumes your influxctl configuration file is located at ./content/influxdb/cloud-dedicated/config.toml. + # The following mount assumes your influxctl configuration file is located at ./content/influxdb3/cloud-dedicated/config.toml. - type: bind - source: ./content/influxdb/cloud-dedicated/config.toml + source: ./content/influxdb3/cloud-dedicated/config.toml target: /root/.config/influxctl/config.toml read_only: true # In your code samples, use `/app/data/` or `data/` to access sample data files from the `static/downloads` directory. @@ -161,9 +161,9 @@ services: command: # In the command, pass file paths to test. # The container preprocesses the files for testing and runs the tests. - - content/influxdb/cloud-serverless/**/*.md + - content/influxdb3/cloud-serverless/**/*.md environment: - - CONTENT_PATH=content/influxdb/cloud-serverless + - CONTENT_PATH=content/influxdb3/cloud-serverless profiles: - test - v3 @@ -180,7 +180,7 @@ services: source: ./test/shared target: /shared - type: bind - source: ./content/influxdb/cloud-serverless/.env.test + source: ./content/influxdb3/cloud-serverless/.env.test target: /app/.env.test read_only: true # In your code samples, use `/app/data/` or `data/` to access sample data files from the `static/downloads` directory. @@ -211,9 +211,9 @@ services: command: # In the command, pass file paths to test. # The container preprocesses the files for testing and runs the tests. - - content/influxdb/clustered/**/*.md + - content/influxdb3/clustered/**/*.md environment: - - CONTENT_PATH=content/influxdb/clustered + - CONTENT_PATH=content/influxdb3/clustered profiles: - test - v3 @@ -230,12 +230,12 @@ services: source: ./test/shared target: /shared - type: bind - source: ./content/influxdb/clustered/.env.test + source: ./content/influxdb3/clustered/.env.test target: /app/.env.test read_only: true - # The following mount assumes your influxctl configuration file is located at ./content/influxdb/clustered/config.toml. + # The following mount assumes your influxctl configuration file is located at ./content/influxdb3/clustered/config.toml. - type: bind - source: ./content/influxdb/clustered/config.toml + source: ./content/influxdb3/clustered/config.toml target: /root/.config/influxctl/config.toml read_only: true # In your code samples, use `/app/data/` or `data/` to access sample data files from the `static/downloads` directory. diff --git a/content/influxdb/cloud/write-data/_index.md b/content/influxdb/cloud/write-data/_index.md index 0e9060534f..a8c2f6527b 100644 --- a/content/influxdb/cloud/write-data/_index.md +++ b/content/influxdb/cloud/write-data/_index.md @@ -12,7 +12,7 @@ menu: name: Write data influxdb/cloud/tags: [write, line protocol] related: - - /influxdb/cloud/api/#tag/Write, InfluxDB API /write endpoint + - /influxdb/cloud/api/#tag/Write, InfluxDB v1 API /write endpoint - /influxdb/cloud/reference/syntax/line-protocol - /influxdb/cloud/reference/syntax/annotated-csv - /influxdb/cloud/reference/cli/influx/write diff --git a/content/influxdb/cloud/write-data/troubleshoot.md b/content/influxdb/cloud/write-data/troubleshoot.md index ec065866f8..a19bfe8cc3 100644 --- a/content/influxdb/cloud/write-data/troubleshoot.md +++ b/content/influxdb/cloud/write-data/troubleshoot.md @@ -11,7 +11,7 @@ menu: parent: Write data influxdb/cloud/tags: [write, line protocol, errors] related: - - /influxdb/cloud/api/#tag/Write, InfluxDB API /write endpoint + - /influxdb/cloud/api/#tag/Write, InfluxDB v1 API /write endpoint - /influxdb/cloud/reference/internals - /influxdb/cloud/reference/cli/influx/write - influxdb/cloud/account-management/limits diff --git a/content/influxdb/v2/api-guide/influxdb-1x/query.md b/content/influxdb/v2/api-guide/influxdb-1x/query.md index b236d74e0b..2236984305 100644 --- a/content/influxdb/v2/api-guide/influxdb-1x/query.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/query.md @@ -117,7 +117,7 @@ The following example: ############################################################################## curl --get "http://{{< influxdb/host >}}/query" \ - --user "INFLUX_USERNAME":"INFLUX_PASSWORD_OR_TOKEN" \ + --user "INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN" \ --data-urlencode "db=BUCKET_NAME" \ --data-urlencode "q=SELECT * FROM cpu_usage" ``` @@ -139,7 +139,7 @@ curl --get "http://{{< influxdb/host >}}/query" \ curl \ --request POST \ "http://{{< influxdb/host >}}/query?db=DATABASE_NAME&rp=RETENTION_POLICY" \ - --user "INFLUX_USERNAME":"INFLUX_PASSWORD_OR_TOKEN" \ + --user "INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN" \ --header "Content-type: application/vnd.influxql" \ --data "SELECT * FROM cpu_usage WHERE time > now() - 1h" ``` diff --git a/content/influxdb/v2/write-data/_index.md b/content/influxdb/v2/write-data/_index.md index 30f6f5f309..43efd81e55 100644 --- a/content/influxdb/v2/write-data/_index.md +++ b/content/influxdb/v2/write-data/_index.md @@ -13,7 +13,7 @@ menu: influxdb/v2/tags: [write, line protocol] related: - /influxdb/v2/write-data/no-code/use-telegraf/ - - /influxdb/v2/api/#tag/Write, InfluxDB API /write endpoint + - /influxdb/v2/api/#tag/Write, InfluxDB v1 API /write endpoint - /influxdb/v2/reference/syntax/line-protocol - /influxdb/v2/reference/syntax/annotated-csv - /influxdb/v2/reference/cli/influx/write diff --git a/content/influxdb/v2/write-data/troubleshoot.md b/content/influxdb/v2/write-data/troubleshoot.md index 3d4fba878e..105e364e03 100644 --- a/content/influxdb/v2/write-data/troubleshoot.md +++ b/content/influxdb/v2/write-data/troubleshoot.md @@ -10,7 +10,7 @@ menu: parent: Write data influxdb/v2/tags: [write, line protocol, errors] related: - - /influxdb/v2/api/v2/#operation/PostLegacyWrite, InfluxDB API /write endpoint + - /influxdb/v2/api/v2/#operation/PostLegacyWrite, InfluxDB v1 API /write endpoint - /influxdb/v2/api/v2/#operation/PostWrite, InfluxDB API /api/v2/write endpoint - /influxdb/v2/reference/internals - /influxdb/v2/reference/cli/influx/write diff --git a/content/influxdb3/cloud-dedicated/guides/api-compatibility/v1/_index.md b/content/influxdb3/cloud-dedicated/guides/api-compatibility/v1/_index.md index 3fd7803287..8861c1bdbd 100644 --- a/content/influxdb3/cloud-dedicated/guides/api-compatibility/v1/_index.md +++ b/content/influxdb3/cloud-dedicated/guides/api-compatibility/v1/_index.md @@ -64,7 +64,7 @@ Learn how to authenticate requests, adjust request parameters for existing v1 wo {{% product-name %}} requires each API request to be authenticated with a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens). -With the InfluxDB v1 API, you can use database tokens in InfluxDB 1.x username and password +With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. - [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) @@ -72,7 +72,7 @@ schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Auth ### Authenticate with a username and password scheme -With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of +With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of username and password to authenticate database reads and writes by passing a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens) as the `password` credential. When authenticating requests to the v1 API `/write` and `/query` endpoints, {{% product-name %}} checks that the `password` (`p`) value is an authorized [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens). @@ -106,7 +106,16 @@ scheme and a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database- {{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh -{{% get-shared-text "api/cloud-dedicated/basic-auth.sh" %}} +####################################### +# Use Basic authentication with a database token +# to query the InfluxDB v1 API +####################################### + + +curl --get "https://{{< influxdb/host >}}/query" \ + --user "any:DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` {{% /code-placeholders %}} @@ -124,7 +133,7 @@ When authenticating requests, {{% product-name %}} checks that the `p` (_passwor ##### Syntax -```sh +```http https://{{< influxdb/host >}}/query/?[u=any]&p=DATABASE_TOKEN https://{{< influxdb/host >}}/write/?[u=any]&p=DATABASE_TOKEN ``` @@ -136,7 +145,18 @@ The following example shows how to use cURL with query string authentication and {{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh -{{% get-shared-text "api/cloud-dedicated/querystring-auth.sh" %}} +####################################### +# Use an InfluxDB 1.x compatible username and password +# to query the InfluxDB v1 API +####################################### +# Use authentication query parameters: +# ?p=DATABASE_TOKEN +####################################### + +curl --get "https://{{< influxdb/host >}}/query" \ + --data-urlencode "p=DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` {{% /code-placeholders %}} diff --git a/content/influxdb3/cloud-dedicated/write-data/_index.md b/content/influxdb3/cloud-dedicated/write-data/_index.md index 0d4b6b22b7..91cfc3d6a6 100644 --- a/content/influxdb3/cloud-dedicated/write-data/_index.md +++ b/content/influxdb3/cloud-dedicated/write-data/_index.md @@ -9,7 +9,7 @@ menu: name: Write data influxdb3/cloud-dedicated/tags: [write, line protocol] # related: -# - /influxdb/cloud/api/#tag/Write, InfluxDB API /write endpoint +# - /influxdb/cloud/api/#tag/Write, InfluxDB v1 API /write endpoint # - /influxdb/cloud/reference/syntax/line-protocol # - /influxdb/cloud/reference/syntax/annotated-csv # - /influxdb/cloud/reference/cli/influx/write diff --git a/content/influxdb3/cloud-serverless/guides/api-compatibility/v1/_index.md b/content/influxdb3/cloud-serverless/guides/api-compatibility/v1/_index.md index 886d052fbc..88d24f7a81 100644 --- a/content/influxdb3/cloud-serverless/guides/api-compatibility/v1/_index.md +++ b/content/influxdb3/cloud-serverless/guides/api-compatibility/v1/_index.md @@ -17,9 +17,10 @@ related: - /influxdb3/cloud-serverless/write-data/api/v1-http/ - /influxdb3/cloud-serverless/reference/api/ list_code_example: | + ```sh curl "https://{{< influxdb/host >}}/query" \ - --user "":"API_TOKEN" \ + --user "any:API_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "rp=RETENTION_POLICY" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" @@ -50,7 +51,7 @@ Learn how to authenticate requests, map databases and retention policies to buck {{% product-name %}} requires each API request to be authenticated with an [API token](/influxdb3/cloud-serverless/admin/tokens/). -With the InfluxDB v1 API, you can use API tokens in InfluxDB 1.x username and password +With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use API tokens in InfluxDB 1.x username and password schemes or in the InfluxDB v2 `Authorization: Token` scheme. - [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) @@ -58,7 +59,7 @@ schemes or in the InfluxDB v2 `Authorization: Token` scheme. ### Authenticate with a username and password scheme -With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of +With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of username and password to authenticate bucket reads and writes by passing an [API token](/influxdb3/cloud-serverless/admin/tokens/) as the `password` credential. When authenticating requests to the v1 API `/write` and `/query` endpoints, {{% product-name %}} checks that the `password` (`p`) value is an authorized [API token](/influxdb3/cloud-serverless/admin/tokens/). {{% product-name %}} ignores the `username` (`u`) parameter in the request. @@ -88,7 +89,7 @@ Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and the The following example shows how to use cURL with the `Basic` authentication scheme and a [token](/influxdb3/cloud-serverless/admin/tokens/): -{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}} +{{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}} ```sh ####################################### # Use Basic authentication with a database token @@ -96,11 +97,12 @@ The following example shows how to use cURL with the `Basic` authentication sche ####################################### curl "https://{{< influxdb/host >}}/query" \ - --user "":"API_TOKEN" \ + --user "any:API_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "rp=RETENTION_POLICY" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` + {{% /code-placeholders %}} Replace the following: @@ -116,9 +118,9 @@ When authenticating requests, {{% product-name %}} checks that the `p` (_passwor ##### Syntax -```sh -https://{{< influxdb/host >}}/query/?[u=any]&p=API_TOKEN -https://{{< influxdb/host >}}/write/?[u=any]&p=API_TOKEN +```http +https://{{< influxdb/host >}}/query/?u=any&p=API_TOKEN +https://{{< influxdb/host >}}/write/?u=any&p=API_TOKEN ``` ##### Example diff --git a/content/influxdb3/cloud-serverless/write-data/_index.md b/content/influxdb3/cloud-serverless/write-data/_index.md index d2edc5114e..cf5a09af68 100644 --- a/content/influxdb3/cloud-serverless/write-data/_index.md +++ b/content/influxdb3/cloud-serverless/write-data/_index.md @@ -9,7 +9,7 @@ menu: name: Write data influxdb3/cloud-serverless/tags: [write, line protocol] related: - - /influxdb3/cloud-serverless/api/#tag/Write, InfluxDB API /write endpoint + - /influxdb3/cloud-serverless/api/#tag/Write, InfluxDB v1 API /write endpoint - /influxdb3/cloud-serverless/reference/syntax/line-protocol - /influxdb3/cloud-serverless/reference/cli/influx/write --- diff --git a/content/influxdb3/clustered/guides/api-compatibility/v1/_index.md b/content/influxdb3/clustered/guides/api-compatibility/v1/_index.md index 575866681f..924dc28459 100644 --- a/content/influxdb3/clustered/guides/api-compatibility/v1/_index.md +++ b/content/influxdb3/clustered/guides/api-compatibility/v1/_index.md @@ -63,7 +63,7 @@ Learn how to authenticate requests, adjust request parameters for existing v1 wo {{% product-name %}} requires each API request to be authenticated with a [database token](/influxdb3/clustered/admin/tokens/#database-tokens). -With the InfluxDB v1 API, you can use database tokens in InfluxDB 1.x username and password +With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. - [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) @@ -71,7 +71,7 @@ schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Auth ### Authenticate with a username and password scheme -With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of +With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of username and password to authenticate database reads and writes by passing a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) as the `password` credential. When authenticating requests to the v1 API `/write` and `/query` endpoints, {{% product-name %}} checks that the `password` (`p`) value is an authorized [database token](/influxdb3/clustered/admin/tokens/#database-tokens). {{% product-name %}} ignores the `username` (`u`) parameter in the request. @@ -104,7 +104,7 @@ The following example shows how to use cURL with the `Basic` authentication sche {{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh curl --get "https://{{< influxdb/host >}}/query" \ - --user "":"DATABASE_TOKEN" \ + --user "any:DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` @@ -122,7 +122,7 @@ When authenticating requests, {{% product-name %}} checks that the `p` (_passwor ##### Syntax -```sh +```http https://{{< influxdb/host >}}/query/?[u=any]&p=DATABASE_TOKEN https://{{< influxdb/host >}}/write/?[u=any]&p=DATABASE_TOKEN ``` diff --git a/content/influxdb3/clustered/write-data/_index.md b/content/influxdb3/clustered/write-data/_index.md index 0345758734..1e67550c4c 100644 --- a/content/influxdb3/clustered/write-data/_index.md +++ b/content/influxdb3/clustered/write-data/_index.md @@ -9,7 +9,7 @@ menu: name: Write data influxdb3/clustered/tags: [write, line protocol] # related: -# - /influxdb/cloud/api/#tag/Write, InfluxDB API /write endpoint +# - /influxdb/cloud/api/#tag/Write, InfluxDB v1 API /write endpoint # - /influxdb/cloud/reference/syntax/line-protocol # - /influxdb/cloud/reference/syntax/annotated-csv # - /influxdb/cloud/reference/cli/influx/write diff --git a/content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md b/content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md index a5e9220cae..bfd5b7edb4 100644 --- a/content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md +++ b/content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md @@ -13,13 +13,13 @@ menu: influxdb3/core/tags: [query, influxql, python] metadata: [InfluxQL] related: - - /influxdb3/core/api-compatibility/v1/ + - /influxdb3/core/write-data/http-api/compatibility-apis/ aliases: - /influxdb3/core/query-data/influxql/execute-queries/influxdb-v1-api/ list_code_example: | ```sh curl --get http://{{< influxdb/host >}}/query \ - --header "Authorization: Token DATABASE_TOKEN" \ + --header "Authorization: Token AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` diff --git a/content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md b/content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md index d9757a7901..2de22725ea 100644 --- a/content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md +++ b/content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md @@ -16,7 +16,7 @@ related: list_code_example: | ```sh curl --get http://{{< influxdb/host >}}/api/v3/query_sql \ - --header "Authorization: Token DATABASE_TOKEN" \ + --header "Authorization: Token AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` diff --git a/content/influxdb3/core/reference/client-libraries/flight/python-flight.md b/content/influxdb3/core/reference/client-libraries/flight/python-flight.md index 8803a8a6ec..8ecc765224 100644 --- a/content/influxdb3/core/reference/client-libraries/flight/python-flight.md +++ b/content/influxdb3/core/reference/client-libraries/flight/python-flight.md @@ -38,7 +38,7 @@ list_code_example: | "query_type": "sql" })) - token = (b"authorization", bytes(f"Bearer DATABASE_TOKEN".encode('utf-8'))) + token = (b"authorization", bytes(f"Bearer AUTH_TOKEN".encode('utf-8'))) options = FlightCallOptions(headers=[token]) client = FlightClient(f"grpc+tls://{{< influxdb/host >}}:443") diff --git a/content/influxdb3/core/reference/client-libraries/v3/python.md b/content/influxdb3/core/reference/client-libraries/v3/python.md index 8a11534379..1802a97ed2 100644 --- a/content/influxdb3/core/reference/client-libraries/v3/python.md +++ b/content/influxdb3/core/reference/client-libraries/v3/python.md @@ -22,7 +22,7 @@ list_code_example: | from influxdb_client_3 import InfluxDBClient3 client = InfluxDBClient3(host=f"{{< influxdb/host >}}", - database=f"DATABASE_NAME", token=f"DATABASE_TOKEN") + database=f"DATABASE_NAME", token=f"AUTH_TOKEN") ``` --> diff --git a/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md b/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md index f91e0c6c85..ea2b8ba2f1 100644 --- a/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md +++ b/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md @@ -13,7 +13,7 @@ menu: influxdb3/enterprise/tags: [query, influxql, python] metadata: [InfluxQL] related: - - /influxdb3/enterprise/api-compatibility/v1/ + - /influxdb3/enterprise/write-data/http-api/compatibility-apis/ aliases: - /influxdb3/enterprise/query-data/influxql/execute-queries/influxdb-v1-api/ list_code_example: | diff --git a/content/shared/influxdb3-admin/tokens/_index.md b/content/shared/influxdb3-admin/tokens/_index.md index b2591ef980..e06eb3aceb 100644 --- a/content/shared/influxdb3-admin/tokens/_index.md +++ b/content/shared/influxdb3-admin/tokens/_index.md @@ -54,22 +54,32 @@ The `Authorization: Bearer AUTH_TOKEN` scheme works with all HTTP API endpoints The following examples use `curl` to show to authenticate to the HTTP API. - -{{% code-placeholders "YOUR_AUTH_TOKEN" %}} +{{% code-placeholders "AUTH_TOKEN" %}} ```bash # Add your token to the HTTP Authorization header curl "http://{{< influxdb/host >}}/api/v3/query_sql" \ - --header "Authorization: Bearer YOUR_AUTH_TOKEN" \ + --header "Authorization: Bearer AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'" ``` +{{% /code-placeholders %}} ### Authenticate using v1 and v2 compatibility +InfluxDB 3 provides compatibility with InfluxDB v1 and v2 APIs, allowing you to use the same authentication methods as in those versions. +With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password +scheme. +With the InfluxDB v2-compatible `/api/v2/write` endpoint, you can use tokens in the InfluxDB v2 `Authorization: Token` scheme or in the OAuth `Authorization: Bearer` scheme. + +The following examples show how to authenticate with the InfluxDB v1-compatible and v2-compatible APIs +in InfluxDB 3: + +{{% code-placeholders "AUTH_TOKEN" %}} + ```bash # Token scheme with v2 /api/v2/write curl http://localhost:8181/api/v2/write\?bucket\=DATABASE_NAME \ - --header "Authorization: Token YOUR_AUTH_TOKEN" \ + --header "Authorization: Token AUTH_TOKEN" \ --data-raw "home,room=Kitchen temp=23.5 1622547800" ``` @@ -78,14 +88,14 @@ curl http://localhost:8181/api/v2/write\?bucket\=DATABASE_NAME \ # Username is ignored, but required for the request # Password is your auth token encoded in base64 curl "http://localhost:8181/write?db=DATABASE_NAME" \ - --user "admin:YOUR_AUTH_TOKEN" \ + --user "any:AUTH_TOKEN" \ --data-raw "home,room=Kitchen temp=23.5 1622547800" ``` ```bash # URL auth parameters with v1 /write # Username is ignored, but required for the request -curl "http://localhost:8181/write?db=DATABASE_NAME&u=admin&p=YOUR_AUTH_TOKEN" \ +curl "http://localhost:8181/write?db=DATABASE_NAME&u=any&p=AUTH_TOKEN" \ --data-raw "home,room=Kitchen temp=23.5 1622547800" ``` {{% /code-placeholders %}} @@ -94,7 +104,7 @@ curl "http://localhost:8181/write?db=DATABASE_NAME&u=admin&p=YOUR_AUTH_TOKEN" \ Replace the following with your values: -- {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link %}} +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link %}} - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases) you want to query To use tokens with other clients for {{< product-name >}}, diff --git a/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md b/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md index 810c075ae3..cb1b1da78a 100644 --- a/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md +++ b/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md @@ -17,29 +17,158 @@ Use the v1 `/query` endpoint and the `GET` request method to query data with Inf {{< api-endpoint endpoint="http://{{< influxdb/host >}}/query" method="get" api-ref="/influxdb3/version/api/#tag/Query" >}} -Provide the following with your request: +## Authenticate API requests -- **Headers:** - - **Authorization:** `Bearer AUTH_TOKEN` -- **Query parameters:** - - **db**: the database to query - - **rp**: Optional: the retention policy to query - - **q**: URL-encoded InfluxQL query +{{< product-name >}} requires each API request to be authenticated with a +{{% token-link %}}. +With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password +schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. -{{% code-placeholders "(DATABASE|AUTH)_(NAME|TOKEN)" %}} +- [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) +- [Authenticate with a token scheme](#authenticate-with-a-token-scheme) + +### Authenticate with a username and password scheme + +With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use the InfluxDB 1.x convention of +username and password to authenticate database reads by passing a {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}} as the `password` credential. +When authenticating requests to the v1 API `/query` endpoint, {{< product-name >}} checks that the `password` (`p`) value is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}}. +{{< product-name >}} ignores the `username` (`u`) parameter in the request. + +Use one of the following authentication schemes with clients that support Basic authentication or query parameters: + +- [Basic authentication](#basic-authentication) +- [Query string authentication](#query-string-authentication) + +#### Basic authentication + +Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/query` requests. +When authenticating requests, {{< product-name >}} checks that the `password` part of the decoded credential is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}}. +{{< product-name >}} ignores the `username` part of the decoded credential. + +##### Syntax + +```http +Authorization: Basic +``` + +Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. + +##### Example + +The following example shows how to use cURL with the `Basic` authentication scheme: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh -curl --get https://{{< influxdb/host >}}/query \ - --header "Authorization: Bearer AUTH_TOKEN" \ +curl --get "https://{{< influxdb/host >}}/query" \ + --user "any:DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM home" +``` +{{% /code-placeholders %}} + +#### Query string authentication + +In the URL, pass the `p` query parameter to authenticate `/query` requests. +When authenticating requests, {{< product-name >}} checks that the `p` (_password_) value is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}} and ignores the `u` (_username_) parameter. + +##### Syntax + +```sh +https://{{< influxdb/host >}}/query/?u=any&p=DATABASE_TOKEN +``` + +##### Example + +The following example shows how to use cURL with query string authentication: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl --get "https://{{< influxdb/host >}}/query" \ + --data-urlencode "p=DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM home" +``` +{{% /code-placeholders %}} + +### Authenticate with a token scheme + +Use the `Authorization: Bearer` or the `Authorization: Token` scheme to pass a {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}} for authenticating +v1 API `/query` requests. + +`Bearer` and `Token` are equivalent in {{< product-name >}}. +The `Token` scheme is used in the InfluxDB 2.x API. +`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14). +Support for one or the other may vary across InfluxDB API clients. + +#### Syntax + +```http +Authorization: Bearer DATABASE_TOKEN +``` + +```http +Authorization: Token DATABASE_TOKEN +``` + +#### Examples + +Use `Bearer` to authenticate a query request: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl --get "https://{{< influxdb/host >}}/query" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" ``` {{% /code-placeholders %}} +Use `Token` to authenticate a query request: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl --get "https://{{< influxdb/host >}}/query" \ + --header "Authorization: Token DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM home" +``` +{{% /code-placeholders %}} + +## Query parameters + +For {{< product-name >}} v1 API `/query` requests, set parameters as listed in the following table: + +Parameter | Allowed in | Ignored | Value +----------|------------|---------|------------------------------------------------------------------------- +`chunked` | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. +`chunked_size` | Query string | Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. +`db` {{% req " \*" %}} | Query string | Honored | Database name +`epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) +`p` | Query string | Honored | For [query string authentication](#query-string-authentication), a {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}} +`pretty` | Query string | Ignored | N/A +`q` {{% req " \*" %}} | Query string | Honored | URL-encoded InfluxQL query +`rp` | Query string | Honored, but discouraged | Retention policy +`u` | Query string | Ignored | For [query string authentication](#query-string-authentication), any arbitrary string +`Authorization` | Header | Honored | `Bearer DATABASE_TOKEN`, `Token DATABASE_TOKEN`, or `Basic ` + +{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}} + +### Timestamp precision + +Use one of the following values for timestamp precision: + +- `ns`: nanoseconds +- `us`: microseconds +- `ms`: milliseconds +- `s`: seconds +- `m`: minutes +- `h`: hours + Replace the following configuration values: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases/) to query -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: your {{< product-name >}} {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}} ## Return results as JSON or CSV @@ -48,10 +177,10 @@ By default, the `/query` endpoint returns results in **JSON**, but it can also return results in **CSV**. To return results as CSV, include the `Accept` header with the `application/csv` or `text/csv` MIME type: -{{% code-placeholders "(DATABASE|AUTH)_(NAME|TOKEN)" %}} +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh curl --get https://{{< influxdb/host >}}/query \ - --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Accept: application/csv" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" diff --git a/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md index 41dc335aab..fc7dfa6edc 100644 --- a/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md +++ b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md @@ -20,6 +20,69 @@ compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2 {{}} +### Authenticate v2 API requests + +{{< product-name >}} requires each API request to be authenticated with a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}. + +Use the `Authorization: Bearer` or `Authorization: Token` scheme to authenticate v2 API write requests: + +#### Syntax + +```http +Authorization: Bearer DATABASE_TOKEN +``` + +```http +Authorization: Token DATABASE_TOKEN +``` + +#### Examples + +Use `Bearer` to authenticate a v2 write request: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl -i "https://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME&precision=s" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' +``` +{{% /code-placeholders %}} + +Use `Token` to authenticate a v2 write request: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl -i "https://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME&precision=s" \ + --header "Authorization: Token DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' +``` +{{% /code-placeholders %}} + +### v2 API write parameters + +For {{< product-name >}} v2 API `/api/v2/write` requests, set parameters as listed in the following table: + +Parameter | Allowed in | Ignored | Value +----------|------------|---------|------------------------------------------------------------------------- +`bucket` {{% req " \*" %}} | Query string | Honored | Database name +`precision` | Query string | Honored | [Timestamp precision](#timestamp-precision-v2) +`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed) +`Authorization` | Header | Honored | `Bearer DATABASE_TOKEN` or `Token DATABASE_TOKEN` + +{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}} + +#### Timestamp precision {#timestamp-precision-v2} + +Use one of the following `precision` values in v2 API `/api/v2/write` requests: + +- `ns`: nanoseconds +- `us`: microseconds +- `ms`: milliseconds +- `s`: seconds +- `m`: minutes +- `h`: hours ## InfluxDB v1 compatibility @@ -27,3 +90,251 @@ The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility {{}} +### Authenticate v1 API requests + +{{< product-name >}} requires each API request to be authenticated with a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}. +With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password +schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. + +- [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) +- [Authenticate with a token scheme](#authenticate-with-a-token-scheme) + +#### Authenticate with a username and password scheme + +With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of +username and password to authenticate database writes by passing a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} as the `password` credential. +When authenticating requests to the v1 API `/write` endpoint, {{< product-name >}} checks that the `password` (`p`) value is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}. +{{< product-name >}} ignores the `username` (`u`) parameter in the request. + +Use one of the following authentication schemes with clients that support Basic authentication or query parameters: + +- [Basic authentication](#basic-authentication-v1) +- [Query string authentication](#query-string-authentication-v1) + +##### Basic authentication {#basic-authentication-v1} + +Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` requests. +When authenticating requests, {{< product-name >}} checks that the `password` part of the decoded credential is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}. +{{< product-name >}} ignores the `username` part of the decoded credential. + +###### Syntax + +```http +Authorization: Basic +``` + +Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. + +###### Example + +The following example shows how to use cURL with the `Basic` authentication scheme: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s" \ + --user "any:DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' +``` +{{% /code-placeholders %}} + +##### Query string authentication {#query-string-authentication-v1} + +In the URL, pass the `p` query parameter to authenticate `/write` requests. +When authenticating requests, {{< product-name >}} checks that the `p` (_password_) value is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} and ignores the `u` (_username_) parameter. + +###### Syntax + +```sh +https://{{< influxdb/host >}}/write/?u=any&p=DATABASE_TOKEN +``` + +###### Example + +The following example shows how to use cURL with query string authentication: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s&p=DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' +``` +{{% /code-placeholders %}} + +#### Authenticate with a token scheme + +Use the `Authorization: Bearer` or the `Authorization: Token` scheme to pass a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} for authenticating +v1 API `/write` requests. + +`Bearer` and `Token` are equivalent in {{< product-name >}}. +The `Token` scheme is used in the InfluxDB 2.x API. +`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14). +Support for one or the other may vary across InfluxDB API clients. + +##### Syntax + +```http +Authorization: Bearer DATABASE_TOKEN +``` + +```http +Authorization: Token DATABASE_TOKEN +``` + +##### Examples + +Use `Bearer` to authenticate a v1 write request: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' +``` +{{% /code-placeholders %}} + +Use `Token` to authenticate a v1 write request: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```sh +curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s" \ + --header "Authorization: Token DATABASE_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary 'home,room=kitchen temp=72 1641024000' +``` +{{% /code-placeholders %}} + +### v1 API write parameters + +For {{< product-name >}} v1 API `/write` requests, set parameters as listed in the following table: + +Parameter | Allowed in | Ignored | Value +----------|------------|---------|------------------------------------------------------------------------- +`consistency` | Query string | Ignored | N/A +`db` {{% req " \*" %}} | Query string | Honored | Database name +`precision` | Query string | Honored | [Timestamp precision](#timestamp-precision-v1) +`rp` | Query string | Honored, but discouraged | Retention policy +`u` | Query string | Ignored | For [query string authentication](#query-string-authentication-v1), any arbitrary string +`p` | Query string | Honored | For [query string authentication](#query-string-authentication-v1), a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} +`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed) +`Authorization` | Header | Honored | `Bearer DATABASE_TOKEN`, `Token DATABASE_TOKEN`, or `Basic ` + +{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}} + +#### Timestamp precision {#timestamp-precision-v1} + +Use one of the following `precision` values in v1 API `/write` requests: + +- `ns`: nanoseconds +- `us`: microseconds +- `ms`: milliseconds +- `s`: seconds +- `m`: minutes +- `h`: hours + +## Client library examples + +Use language-specific client libraries with your custom code to write data to {{< product-name >}}. + +### v1 client libraries + +v1 client libraries send data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Node.js](#nodejs) +[Python](#python) +{{% /tabs %}} +{{% tab-content %}} + + +Create a v1 API client using the [node-influx](/influxdb/v1/tools/api_client_libraries/#javascriptnodejs) JavaScript client library: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```js +const Influx = require('influx') + +// Instantiate a client for writing to {{% product-name %}} v1 API +const client = new Influx.InfluxDB({ + host: '{{< influxdb/host >}}', + port: 443, + protocol: 'https', + database: 'DATABASE_NAME', + username: 'ignored', + password: 'DATABASE_TOKEN' +}) +``` +{{% /code-placeholders %}} + + +{{% /tab-content %}} +{{% tab-content %}} + + +Create a v1 API client using the [influxdb-python](/influxdb/v1/tools/api_client_libraries/#python) Python client library: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```py +from influxdb import InfluxDBClient + +# Instantiate a client for writing to {{% product-name %}} v1 API +client = InfluxDBClient( + host='{{< influxdb/host >}}', + ssl=True, + database='DATABASE_NAME', + username='', + password='DATABASE_TOKEN', + headers={'Content-Type': 'text/plain; charset=utf-8'} +) +``` +{{% /code-placeholders %}} + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### v2 client libraries + +v2 client libraries send data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax to the v2 API `/api/v2/write` endpoint. + +For more information about using v2 client libraries, see [v2 client libraries](/influxdb3/version/reference/client-libraries/v2/). + +## Telegraf configuration + +If you have existing v1 workloads that use Telegraf, +you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data. + +The following table shows `outputs.influxdb` plugin parameters and values for writing to the {{< product-name >}} v1 API: + +Parameter | Ignored | Value +----------|---------|------------------------------------------------------------------------------------------- +`database` | Honored | Database name +`retention_policy` | Honored, but discouraged | [Duration](/influxdb3/version/reference/glossary/#duration) +`username` | Ignored | String or empty +`password` | Honored | {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} +`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed) +`skip_database_creation` | Ignored | N/A (see how to [create a database](/influxdb3/version/admin/databases/create/)) + +To configure the v1.x output plugin for writing to {{< product-name >}}, add the following `outputs.influxdb` configuration in your `telegraf.conf` file: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```toml +[[outputs.influxdb]] + urls = ["https://{{< influxdb/host >}}"] + database = "DATABASE_NAME" + skip_database_creation = true + retention_policy = "" + username = "ignored" + password = "DATABASE_TOKEN" + content_encoding = "gzip" +``` +{{% /code-placeholders %}} + +Replace the following configuration values: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of the [database](/influxdb3/version/admin/databases/) to write to +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: + your {{< product-name >}} {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} + diff --git a/shared/text/api/cloud-dedicated/basic-auth.sh b/shared/text/api/cloud-dedicated/basic-auth.sh deleted file mode 100644 index 44e6790682..0000000000 --- a/shared/text/api/cloud-dedicated/basic-auth.sh +++ /dev/null @@ -1,10 +0,0 @@ -####################################### -# Use Basic authentication with a database token -# to query the InfluxDB v1 API -####################################### - - -curl --get "https://cluster-id.a.influxdb.io/query" \ - --user "":"DATABASE_TOKEN" \ - --data-urlencode "db=DATABASE_NAME" \ - --data-urlencode "q=SELECT * FROM MEASUREMENT" diff --git a/shared/text/api/cloud-dedicated/querystring-auth.sh b/shared/text/api/cloud-dedicated/querystring-auth.sh deleted file mode 100644 index 8298b5dcbf..0000000000 --- a/shared/text/api/cloud-dedicated/querystring-auth.sh +++ /dev/null @@ -1,12 +0,0 @@ -####################################### -# Use an InfluxDB 1.x compatible username and password -# to query the InfluxDB v1 API -####################################### -# Use authentication query parameters: -# ?p=DATABASE_TOKEN -####################################### - -curl --get "https://cluster-id.a.influxdb.io/query" \ - --data-urlencode "p=DATABASE_TOKEN" \ - --data-urlencode "db=DATABASE_NAME" \ - --data-urlencode "q=SELECT * FROM MEASUREMENT"