Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'master' into jdstrand/use-modern-gpg-key

pull/6196/head
Jason Stirnaman 2025-07-08 15:30:20 -05:00 committed by GitHub
parent adb9a6e857 90da0f261c
commit 108e5e038c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
31 changed files with 1174 additions and 267 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
api-docs/influxdb/cloud/v2/ref.yml
View File

@ -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 |
|:------------|:----------------------------|

10
api-docs/influxdb/v2/v2/ref.yml
View File

@ -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 |
|:------------|:----------------------------|

126
api-docs/influxdb3/cloud-dedicated/v2/ref.yml
View File

@ -63,12 +63,14 @@ tags:
name: API compatibility
x-traitTag: true
- description: |
Use one of the following schemes to authenticate to the InfluxDB API:
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
- [Bearer authentication](#section/Authentication/BearerAuthentication)
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
| 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 |
<!-- ReDoc-Inject: <security-definitions> -->
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 requests.
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.
Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3.
### Syntax
```http
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>
```
Replace the following:
- **`[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
The following example shows how to use cURL with query string authentication and a [database token](/influxdb3/cloud-dedicated/admin/tokens/).
```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'
```
```sh
Replace the following:
- **`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.
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.
@ -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

2
api-docs/influxdb3/cloud-serverless/v2/ref.yml
View File

@ -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 |
|:------------|:----------------------------|

130
api-docs/influxdb3/clustered/v2/ref.yml
View File

@ -63,12 +63,14 @@ tags:
name: API compatibility
x-traitTag: true
- description: |
Use one of the following schemes to authenticate to the InfluxDB API:
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
- [Bearer authentication](#section/Authentication/BearerAuthentication)
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
| 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 |
<!-- ReDoc-Inject: <security-definitions> -->
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 <base64-encoded [USERNAME]:DATABASE_TOKEN>
```
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.
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.
@ -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

261
api-docs/influxdb3/core/v3/ref.yml
View File

@ -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.
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
The InfluxDB 3 API uses tokens for authentication.
To authenticate, include the `Authorization` header in your request with the value `Bearer <token>`.
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/)
| 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 |
<!-- ReDoc-Inject: <security-definitions> -->
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 <base64-encoded USERNAME:AUTH_TOKEN>` - 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 <base64-encoded USERNAME:AUTH_TOKEN>` - 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:

266
api-docs/influxdb3/enterprise/v3/ref.yml
View File

@ -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.
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
The InfluxDB 3 API uses tokens for authentication.
To authenticate, include the `Authorization` header in your request with the value `Bearer <token>`.
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/)
| 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 |
<!-- ReDoc-Inject: <security-definitions> -->
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 <base64-encoded USERNAME:AUTH_TOKEN>` - 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 <base64-encoded USERNAME:AUTH_TOKEN>` - 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 <base64-encoded [USERNAME]:AUTH_TOKEN>
```
### 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:

28
compose.yaml
View File

@ -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/<FILE.lp>` or `data/<FILE.lp>` 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/<FILE.lp>` or `data/<FILE.lp>` 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/<FILE.lp>` or `data/<FILE.lp>` to access sample data files from the `static/downloads` directory.

2
content/influxdb/cloud/write-data/_index.md
View File

@ -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

2
content/influxdb/cloud/write-data/troubleshoot.md
View File

@ -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

4
content/influxdb/v1/introduction/install.md
View File

@ -214,12 +214,12 @@ Quick start:
```bash
# Pull the latest InfluxDB v1.x image
docker pull influxdb:{{< latest-patch version="1" >}}
docker pull influxdb:{{< latest-patch >}}
# Start InfluxDB with persistent storage
docker run -p 8086:8086 \
-v $PWD/data:/var/lib/influxdb \
influxdb:{{< latest-patch version="1" >}}
influxdb:{{< latest-patch >}}
```
{{% /tab-content %}}

14
content/influxdb/v1/introduction/install/docker.md
View File

@ -27,7 +27,7 @@ This guide covers Docker installation, configuration, and initialization options
### Pull the InfluxDB v1.x image
```bash
docker pull influxdb:{{< latest-patch version="1" >}}
docker pull influxdb:{{< latest-patch >}}
```
### Start InfluxDB
@ -37,7 +37,7 @@ Start a basic InfluxDB container with persistent storage:
```bash
docker run -p 8086:8086 \
-v $PWD/data:/var/lib/influxdb \
influxdb:{{< latest-patch version="1" >}}
influxdb:{{< latest-patch >}}
```
InfluxDB is now running and available at http://localhost:8086.
@ -54,7 +54,7 @@ docker run -p 8086:8086 \
-e INFLUXDB_REPORTING_DISABLED=true \
-e INFLUXDB_HTTP_AUTH_ENABLED=true \
-e INFLUXDB_HTTP_LOG_ENABLED=true \
influxdb:{{< latest-patch version="1" >}}
influxdb:{{< latest-patch >}}
```
### Using a configuration file
@ -62,7 +62,7 @@ docker run -p 8086:8086 \
Generate a default configuration file:
```bash
docker run --rm influxdb:{{< latest-patch version="1" >}} influxd config > influxdb.conf
docker run --rm influxdb:{{< latest-patch >}} influxd config > influxdb.conf
```
Start InfluxDB with your custom configuration:
@ -71,7 +71,7 @@ Start InfluxDB with your custom configuration:
docker run -p 8086:8086 \
-v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \
-v $PWD/data:/var/lib/influxdb \
influxdb:{{< latest-patch version="1" >}}
influxdb:{{< latest-patch >}}
```
## Initialize InfluxDB
@ -91,7 +91,7 @@ docker run -p 8086:8086 \
-e INFLUXDB_HTTP_AUTH_ENABLED=true \
-e INFLUXDB_ADMIN_USER=admin \
-e INFLUXDB_ADMIN_PASSWORD=supersecretpassword \
influxdb:{{< latest-patch version="1" >}}
influxdb:{{< latest-patch >}}
```
Environment variables for user creation:
@ -128,7 +128,7 @@ Run with initialization scripts:
docker run -p 8086:8086 \
-v $PWD/data:/var/lib/influxdb \
-v $PWD/init-scripts:/docker-entrypoint-initdb.d \
influxdb:{{< latest-patch version="1" >}}
influxdb:{{< latest-patch >}}
```
Supported script types:

4
content/influxdb/v2/api-guide/influxdb-1x/query.md
View File

@ -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"
```

2
content/influxdb/v2/write-data/_index.md
View File

@ -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

2
content/influxdb/v2/write-data/troubleshoot.md
View File

@ -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

30
content/influxdb3/cloud-dedicated/guides/api-compatibility/v1/_index.md
View File

@ -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 %}}

2
content/influxdb3/cloud-dedicated/write-data/_index.md
View File

@ -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

18
content/influxdb3/cloud-serverless/guides/api-compatibility/v1/_index.md
View File

@ -17,9 +17,10 @@ related:
- /influxdb3/cloud-serverless/write-data/api/v1-http/
- /influxdb3/cloud-serverless/reference/api/
list_code_example: |
<!-- pytest.mark.skip -->
```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

2
content/influxdb3/cloud-serverless/write-data/_index.md
View File

@ -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
---

8
content/influxdb3/clustered/guides/api-compatibility/v1/_index.md
View File

@ -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
```

2
content/influxdb3/clustered/write-data/_index.md
View File

@ -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

4
content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md
View File

@ -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"
```

2
content/influxdb3/core/query-data/execute-queries/influxdb-v3-api.md
View File

@ -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"
```

2
content/influxdb3/core/reference/client-libraries/flight/python-flight.md
View File

@ -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")

2
content/influxdb3/core/reference/client-libraries/v3/python.md
View File

@ -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")
```
-->
<!--pytest-codeblocks:cont-->

2
content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md
View File

@ -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: |

24
content/shared/influxdb3-admin/tokens/_index.md
View File

@ -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 >}},

155
content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md
View File

@ -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 <base64-encoded [USERNAME]:DATABASE_TOKEN>
```
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 <base64 [USERNAME]:DATABASE_TOKEN>`
{{% 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"

311
content/shared/influxdb3-write-guides/http-api/compatibility-apis.md
View File

@ -20,6 +20,69 @@ compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2
{{<api-endpoint endpoint="/api/v2/write?bucket=mydb&precision=ns" method="post" api-ref="/influxdb3/version/api/v3/#operation/PostV1Write" >}}
### 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
{{<api-endpoint endpoint="/write?db=mydb&precision=ns" method="post" api-ref="/influxdb3/version/api/v3/#operation/PostV2Write" >}}
### 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 <base64-encoded [USERNAME]:DATABASE_TOKEN>
```
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 <base64 [USERNAME]:DATABASE_TOKEN>`
{{% 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 %}}
<!-- Start NodeJS -->
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 %}}
<!-- End NodeJS -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- Start Python -->
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 %}}
<!-- End Python -->
{{% /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 %}}

10
shared/text/api/cloud-dedicated/basic-auth.sh
View File

@ -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"

12
shared/text/api/cloud-dedicated/querystring-auth.sh
View File

@ -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"