diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c25c79fff..bbdac5194 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -82,7 +82,7 @@ GitHub Copilot should help document InfluxData products by creating clear, accur product_version: weight: # Page order (1-99, 101-199, etc.) ``` - +- Follow the shortcode documentation in `CONTRIBUTING.md` - Use provided shortcodes correctly: - Notes/warnings: `{{% note %}}`, `{{% warn %}}` - Product-specific: `{{% enterprise %}}`, `{{% cloud %}}` @@ -126,6 +126,7 @@ Table: keys: [_start, _stop, _field, _measurement] ## API Documentation +- `/api-docs` contains OpenAPI spec files used for API reference documentation - Follow OpenAPI specification patterns - Match REST API examples to current implementation - Include complete request/response examples diff --git a/.gitignore b/.gitignore index 7faf70c94..5dbb8bcae 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ node_modules /content/influxdb*/**/api/**/*.html !api-docs/**/.config.yml /api-docs/redoc-static.html* +/cypress/screenshots/* .vscode/* .idea **/config.toml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ece943143..7edb6fd7b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1633,6 +1633,31 @@ Supported argument values: {{< influxdb/host "serverless" >}} ``` +### User-populated placeholders + +Use the `code-placeholders` shortcode to format placeholders +as text fields that users can populate with their own values. +The shortcode takes a regular expression for matching placeholder names. +Use the `code-placeholder-key` shortcode to format the placeholder names in +text that describes the placeholder--for example: + +``` +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} +```sh +curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ + --header "Authorization: Token API_TOKEN" \ + --data-binary @path/to/line-protocol.txt +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME` and `RETENTION_POLICY`{{% /code-placeholder-key %}}: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to +- {{% code-placeholder-key %}}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) +- {{% code-placeholder-key %}}`PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) +- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) +``` + ## InfluxDB API documentation InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full diff --git a/api-docs/influxdb3/core/v3/content/tag-groups.yml b/api-docs/influxdb3/core/v3/content/tag-groups.yml index 5289ddb33..364d5e794 100644 --- a/api-docs/influxdb3/core/v3/content/tag-groups.yml +++ b/api-docs/influxdb3/core/v3/content/tag-groups.yml @@ -2,11 +2,14 @@ tags: - Quick start - Authentication + - Cache data - Common parameters - Response codes - Compatibility endpoints - - Data I/O - - Databases + - Database - Processing engine - Server information - - Tables + - Table + - Token + - Query data + - Write data diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml index 5d0abe7df..7d1ba6a38 100644 --- a/api-docs/influxdb3/core/v3/ref.yml +++ b/api-docs/influxdb3/core/v3/ref.yml @@ -43,8 +43,50 @@ security: tags: - name: Authentication description: | - During the Beta phase, InfluxDB 3 Core does not require authentication. + 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/authentication/) x-traitTag: true + - name: Cache data + description: | + Manage the in-memory cache. + + #### Distinct Value Cache + + The Distinct Value Cache (DVC) lets you cache distinct + values of one or more columns in a table, improving the performance of + queries that return distinct tag and field values. + + The DVC is an in-memory cache that stores distinct values for specific columns + in a table. When you create an DVC, you can specify what columns' distinct + values to cache, the maximum number of distinct value combinations to cache, and + the maximum age of cached values. A DVC is associated with a table, which can + have multiple DVCs. + + #### Last value cache + + The Last Value Cache (LVC) lets you cache the most recent + values for specific fields in a table, improving the performance of queries that + return the most recent value of a field for specific series or the last N values + of a field. + + The LVC is an in-memory cache that stores the last N number of values for + specific fields of series in a table. When you create an LVC, you can specify + what fields to cache, what tags to use to identify each series, and the + number of values to cache for each unique series. + An LVC is associated with a table, which can have multiple LVCs. + + #### Related guides + + - [Manage the Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/) + - [Manage the Last Value Cache](/influxdb3/core/admin/last-value-cache/) - name: Compatibility endpoints description: | InfluxDB 3 provides compatibility endpoints for InfluxDB 1.x and InfluxDB 2.x workloads and clients. @@ -72,19 +114,8 @@ tags: ### Server information Server information endpoints such as `/health` and `metrics` are compatible with InfluxDB 1.x and InfluxDB 2.x clients. - - name: Data I/O - description: | - Write and query data - - #### Data flow in InfluxDB 3 Core - - 1. **Incoming writes**: The system validates incoming data and stores it in the write buffer (in memory). If the `no_sync` write option is enabled (`no_sync=true`), the server sends a response to acknowledge the write. - 2. **WAL flush**: Every second (default), the system flushes the write buffer to the Write-Ahead Log (WAL) for persistence in the Object store. If `no_sync=false` (default), the server sends a response to acknowledge the write. - 3. **Query availability**: After WAL persistence completes, data moves to the queryable buffer where it becomes available for queries. By default, the server keeps up to 900 WAL files (15 minutes of data) buffered. - 4. **Long-term storage in Parquet**: Every ten minutes (default), the system persists the oldest data from the queryable buffer to the Object store in Parquet format. InfluxDB keeps the remaining data (the most recent 5 minutes) in memory. - 5. **In-memory cache**: InfluxDB puts Parquet files into an in-memory cache so that queries against the most recently persisted data don't have to go to object storage. - - name: Databases - description: Create, read, update, and delete database and cache resources + - name: Database + description: Manage databases - description: | Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use. @@ -119,28 +150,38 @@ tags: Use Processing engine plugins and triggers to run code and perform tasks for different database events. To get started with the Processing engine, see the [Processing engine and Python plugins](/influxdb3/core/processing-engine/) guide. + - name: Query data + description: Query data using SQL or InfluxQL - name: Quick start description: | - 1. [Check the status](#section/Server-information) of the InfluxDB server. + 1. [Create an admin token](#section/Authentication) for the InfluxDB 3 Core API. ```bash - curl "http://localhost:8181/health" + curl -X POST "http://localhost:8181/api/v3/configure/token/admin" + ``` + 2. [Check the status](#section/Server-information) of the InfluxDB server. + + ```bash + curl "http://localhost:8181/health" \ + --header "Authorization: Bearer ADMIN_TOKEN" ``` - 2. [Write data](#section/Compatibility-endpoints/Write-data) to InfluxDB. + 3. [Write data](#operation/PostWriteLP) to InfluxDB. ```bash - curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto" \ + curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto" + --header "Authorization: Bearer ADMIN_TOKEN" \ --data-raw "home,room=Kitchen temp=72.0 home,room=Living\ room temp=71.5" ``` If all data is written, the response is `204 No Content`. - 3. [Query data](#section/Compatibility-endpoints/Query-data) from InfluxDB. + 4. [Query data](#operation/GetExecuteQuerySQL) from InfluxDB. ```bash curl -G "http://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer ADMIN_TOKEN" \ --data-urlencode "db=sensors" \ --data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \ --data-urlencode "format=jsonl" @@ -156,8 +197,12 @@ tags: x-traitTag: true - name: Server information description: Retrieve server metrics, status, and version information - - name: Tables + - name: Table description: Manage table schemas and data + - name: Token + description: Manage tokens for authentication and authorization + - name: Write data + description: Write data to InfluxDB 3 paths: /write: post: @@ -244,7 +289,7 @@ paths: description: Request entity too large. tags: - Compatibility endpoints - - Data I/O + - Write data /api/v2/write: post: operationId: PostV2Write @@ -327,7 +372,7 @@ paths: description: Request entity too large. tags: - Compatibility endpoints - - Data I/O + - Write data /api/v3/write_lp: post: operationId: PostWriteLP @@ -387,7 +432,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Write data /api/v3/query_sql: get: operationId: GetExecuteQuerySQL @@ -446,7 +491,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data post: operationId: PostExecuteQuerySQL summary: Execute SQL query @@ -485,7 +530,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data /api/v3/query_influxql: get: operationId: GetExecuteInfluxQLQuery @@ -533,7 +578,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data post: operationId: PostExecuteQueryInfluxQL summary: Execute InfluxQL query @@ -572,7 +617,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data /query: get: operationId: GetV1ExecuteQuery @@ -678,7 +723,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data - Compatibility endpoints post: operationId: PostExecuteV1Query @@ -789,7 +834,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data - Compatibility endpoints /health: get: @@ -863,7 +908,7 @@ paths: '404': description: Database not found. tags: - - Databases + - Database post: operationId: PostConfigureDatabase summary: Create a database @@ -884,7 +929,7 @@ paths: '409': description: Database already exists. tags: - - Databases + - Database delete: operationId: DeleteConfigureDatabase summary: Delete a database @@ -901,7 +946,7 @@ paths: '404': description: Database not found. tags: - - Databases + - Database /api/v3/configure/table: post: operationId: PostConfigureTable @@ -923,7 +968,7 @@ paths: '404': description: Database not found. tags: - - Tables + - Table delete: operationId: DeleteConfigureTable summary: Delete a table @@ -945,14 +990,15 @@ paths: '404': description: Table not found. tags: - - Tables + - Table /api/v3/configure/distinct_cache: post: operationId: PostConfigureDistinctCache summary: Create distinct cache description: Creates a distinct cache for a table. tags: - - Tables + - Cache data + - Table requestBody: required: true content: @@ -992,7 +1038,8 @@ paths: '409': description: Cache already exists. tags: - - Tables + - Cache data + - Table delete: operationId: DeleteConfigureLastCache summary: Delete last cache @@ -1019,7 +1066,8 @@ paths: '404': description: Cache not found. tags: - - Tables + - Cache data + - Table /api/v3/configure/processing_engine_trigger: post: operationId: PostConfigureProcessingEngineTrigger @@ -1280,6 +1328,50 @@ paths: description: Processing failure. tags: - Processing engine + /api/v3/configure/token/admin: + post: + operationId: PostCreateAdminToken + summary: Create admin token + description: | + Creates an admin token. + An admin token is a special type of token that has full access to all resources in the system. + + This endpoint is only available in InfluxDB 3 Enterprise. + responses: + '201': + description: | + Success. The admin token has been created. + The response body contains the token string and metadata. + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTokenObject' + '401': + $ref: '#/components/responses/Unauthorized' + tags: + - Authentication + - Token + /api/v3/configure/token/admin/regenerate: + post: + operationId: PostRegenerateAdminToken + summary: Regenerate admin token + description: | + Regenerates an admin token and revokes the previous token with the same name. + + This endpoint is only available in InfluxDB 3 Enterprise. + parameters: [] + responses: + '201': + description: Success. The admin token has been regenerated. + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTokenObject' + '401': + $ref: '#/components/responses/Unauthorized' + tags: + - Authentication + - Token components: parameters: AcceptQueryHeader: @@ -1416,6 +1508,29 @@ components: schema: $ref: '#/components/schemas/QueryRequestObject' schemas: + AdminTokenObject: + type: object + properties: + id: + type: integer + name: + type: string + token: + type: string + hash: + type: string + created_at: + type: string + format: date-time + expiry: + format: date-time + example: + id: 0 + name: _admin + token: apiv3_00xx0Xx0xx00XX0x0 + hash: 00xx0Xx0xx00XX0x0 + created_at: '2025-04-18T14:02:45.331Z' + expiry: null ContentEncoding: type: string enum: @@ -1457,13 +1572,10 @@ components: description: | Acknowledges a successful write without waiting for WAL persistence. - #### Data flow in InfluxDB 3 Core + #### Related - 1. **Incoming writes**: The system validates incoming data and stores it in the write buffer (in memory). If the `no_sync` write option is enabled (`no_sync=true`), the server sends a response to acknowledge the write. - 2. **WAL flush**: Every second (default), the system flushes the write buffer to the Write-Ahead Log (WAL) for persistence in the Object store. If `no_sync=false` (default), the server sends a response to acknowledge the write. - 3. **Query availability**: After WAL persistence completes, data moves to the queryable buffer where it becomes available for queries. By default, the server keeps up to 900 WAL files (15 minutes of data) buffered. - 4. **Long-term storage in Parquet**: Every ten minutes (default), the system persists the oldest data from the queryable buffer to the Object store in Parquet format. InfluxDB keeps the remaining data (the most recent 5 minutes) in memory. - 5. **In-memory cache**: InfluxDB puts Parquet files into an in-memory cache so that queries against the most recently persisted data don't have to go to object storage. + - [Use the HTTP API and client libraries to write data](/influxdb3/core/write-data/api-client-libraries/) + - [Data durability](/influxdb3/core/reference/internals/durability/) PrecisionWriteCompatibility: enum: - ms @@ -1782,11 +1894,14 @@ x-tagGroups: tags: - Quick start - Authentication + - Cache data - Common parameters - Response codes - Compatibility endpoints - - Data I/O - - Databases + - Database - Processing engine - Server information - - Tables + - Table + - Token + - Query data + - Write data diff --git a/api-docs/influxdb3/enterprise/v3/content/tag-groups.yml b/api-docs/influxdb3/enterprise/v3/content/tag-groups.yml index 5289ddb33..364d5e794 100644 --- a/api-docs/influxdb3/enterprise/v3/content/tag-groups.yml +++ b/api-docs/influxdb3/enterprise/v3/content/tag-groups.yml @@ -2,11 +2,14 @@ tags: - Quick start - Authentication + - Cache data - Common parameters - Response codes - Compatibility endpoints - - Data I/O - - Databases + - Database - Processing engine - Server information - - Tables + - Table + - Token + - Query data + - Write data diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml index 69019c77d..28babb0c0 100644 --- a/api-docs/influxdb3/enterprise/v3/ref.yml +++ b/api-docs/influxdb3/enterprise/v3/ref.yml @@ -43,8 +43,50 @@ security: tags: - name: Authentication description: | - During the Beta phase, InfluxDB 3 Enterprise does not require authentication. + 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/authentication/) x-traitTag: true + - name: Cache data + description: | + Manage the in-memory cache. + + #### Distinct Value Cache + + The Distinct Value Cache (DVC) lets you cache distinct + values of one or more columns in a table, improving the performance of + queries that return distinct tag and field values. + + The DVC is an in-memory cache that stores distinct values for specific columns + in a table. When you create an DVC, you can specify what columns' distinct + values to cache, the maximum number of distinct value combinations to cache, and + the maximum age of cached values. A DVC is associated with a table, which can + have multiple DVCs. + + #### Last value cache + + The Last Value Cache (LVC) lets you cache the most recent + values for specific fields in a table, improving the performance of queries that + return the most recent value of a field for specific series or the last N values + of a field. + + The LVC is an in-memory cache that stores the last N number of values for + specific fields of series in a table. When you create an LVC, you can specify + what fields to cache, what tags to use to identify each series, and the + number of values to cache for each unique series. + An LVC is associated with a table, which can have multiple LVCs. + + #### Related guides + + - [Manage the Distinct Value Cache](/influxdb3/enterprise/admin/distinct-value-cache/) + - [Manage the Last Value Cache](/influxdb3/enterprise/admin/last-value-cache/) - name: Compatibility endpoints description: | InfluxDB 3 provides compatibility endpoints for InfluxDB 1.x and InfluxDB 2.x workloads and clients. @@ -72,19 +114,8 @@ tags: ### Server information Server information endpoints such as `/health` and `metrics` are compatible with InfluxDB 1.x and InfluxDB 2.x clients. - - name: Data I/O - description: | - Write and query data - - #### Data flow in InfluxDB 3 Enterprise - - 1. **Incoming writes**: The system validates incoming data and stores it in the write buffer (in memory). If the `no_sync` write option is enabled (`no_sync=true`), the server sends a response to acknowledge the write. - 2. **WAL flush**: Every second (default), the system flushes the write buffer to the Write-Ahead Log (WAL) for persistence in the Object store. If `no_sync=false` (default), the server sends a response to acknowledge the write. - 3. **Query availability**: After WAL persistence completes, data moves to the queryable buffer where it becomes available for queries. By default, the server keeps up to 900 WAL files (15 minutes of data) buffered. - 4. **Long-term storage in Parquet**: Every ten minutes (default), the system persists the oldest data from the queryable buffer to the Object store in Parquet format. InfluxDB keeps the remaining data (the most recent 5 minutes) in memory. - 5. **In-memory cache**: InfluxDB puts Parquet files into an in-memory cache so that queries against the most recently persisted data don't have to go to object storage. - - name: Databases - description: Create, read, update, and delete database and cache resources + - name: Database + description: Manage databases - description: | Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use. @@ -119,28 +150,38 @@ tags: Use Processing engine plugins and triggers to run code and perform tasks for different database events. To get started with the Processing engine, see the [Processing engine and Python plugins](/influxdb3/enterprise/processing-engine/) guide. + - name: Query data + description: Query data using SQL or InfluxQL - name: Quick start description: | - 1. [Check the status](#section/Server-information) of the InfluxDB server. + 1. [Create an admin token](#section/Authentication) for the InfluxDB 3 Enterprise API. ```bash - curl "http://localhost:8181/health" + curl -X POST "http://localhost:8181/api/v3/enterprise/configure/token/admin" + ``` + 2. [Check the status](#section/Server-information) of the InfluxDB server. + + ```bash + curl "http://localhost:8181/health" \ + --header "Authorization: Bearer ADMIN_TOKEN" ``` - 2. [Write data](#section/Compatibility-endpoints/Write-data) to InfluxDB. + 3. [Write data](#operation/PostWriteLP) to InfluxDB. ```bash - curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto" \ + curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto" + --header "Authorization: Bearer ADMIN_TOKEN" \ --data-raw "home,room=Kitchen temp=72.0 home,room=Living\ room temp=71.5" ``` If all data is written, the response is `204 No Content`. - 3. [Query data](#section/Compatibility-endpoints/Query-data) from InfluxDB. + 4. [Query data](#operation/GetExecuteQuerySQL) from InfluxDB. ```bash curl -G "http://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer ADMIN_TOKEN" \ --data-urlencode "db=sensors" \ --data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \ --data-urlencode "format=jsonl" @@ -156,8 +197,12 @@ tags: x-traitTag: true - name: Server information description: Retrieve server metrics, status, and version information - - name: Tables + - name: Table description: Manage table schemas and data + - name: Token + description: Manage tokens for authentication and authorization + - name: Write data + description: Write data to InfluxDB 3 paths: /write: post: @@ -244,7 +289,7 @@ paths: description: Request entity too large. tags: - Compatibility endpoints - - Data I/O + - Write data /api/v2/write: post: operationId: PostV2Write @@ -327,7 +372,7 @@ paths: description: Request entity too large. tags: - Compatibility endpoints - - Data I/O + - Write data /api/v3/write_lp: post: operationId: PostWriteLP @@ -387,7 +432,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Write data /api/v3/query_sql: get: operationId: GetExecuteQuerySQL @@ -446,7 +491,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data post: operationId: PostExecuteQuerySQL summary: Execute SQL query @@ -485,7 +530,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data /api/v3/query_influxql: get: operationId: GetExecuteInfluxQLQuery @@ -533,7 +578,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data post: operationId: PostExecuteQueryInfluxQL summary: Execute InfluxQL query @@ -572,7 +617,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data /query: get: operationId: GetV1ExecuteQuery @@ -678,7 +723,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data - Compatibility endpoints post: operationId: PostExecuteV1Query @@ -789,7 +834,7 @@ paths: '422': description: Unprocessable entity. tags: - - Data I/O + - Query data - Compatibility endpoints /health: get: @@ -863,7 +908,7 @@ paths: '404': description: Database not found. tags: - - Databases + - Database post: operationId: PostConfigureDatabase summary: Create a database @@ -884,7 +929,7 @@ paths: '409': description: Database already exists. tags: - - Databases + - Database delete: operationId: DeleteConfigureDatabase summary: Delete a database @@ -901,7 +946,7 @@ paths: '404': description: Database not found. tags: - - Databases + - Database /api/v3/configure/table: post: operationId: PostConfigureTable @@ -923,7 +968,7 @@ paths: '404': description: Database not found. tags: - - Tables + - Table delete: operationId: DeleteConfigureTable summary: Delete a table @@ -945,14 +990,15 @@ paths: '404': description: Table not found. tags: - - Tables + - Table /api/v3/configure/distinct_cache: post: operationId: PostConfigureDistinctCache summary: Create distinct cache description: Creates a distinct cache for a table. tags: - - Tables + - Cache data + - Table requestBody: required: true content: @@ -992,7 +1038,8 @@ paths: '409': description: Cache already exists. tags: - - Tables + - Cache data + - Table delete: operationId: DeleteConfigureLastCache summary: Delete last cache @@ -1019,7 +1066,8 @@ paths: '404': description: Cache not found. tags: - - Tables + - Cache data + - Table /api/v3/configure/processing_engine_trigger: post: operationId: PostConfigureProcessingEngineTrigger @@ -1280,6 +1328,73 @@ paths: description: Processing failure. tags: - Processing engine + /api/v3/configure/enterprise/token: + post: + operationId: PostCreateResourceToken + summary: Create a resource token + description: | + Creates a resource (fine-grained permissions) token. + A resource token is a token that has access to specific resources in the system. + + This endpoint is only available in InfluxDB 3 Enterprise. + responses: + '201': + description: | + Success. The resource token has been created. + The response body contains the token string and metadata. + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceTokenObject' + '401': + $ref: '#/components/responses/Unauthorized' + tags: + - Authentication + - Token + /api/v3/configure/enterprise/token/admin: + post: + operationId: PostCreateAdminToken + summary: Create admin token + description: | + Creates an admin token. + An admin token is a special type of token that has full access to all resources in the system. + + This endpoint is only available in InfluxDB 3 Enterprise. + responses: + '201': + description: | + Success. The admin token has been created. + The response body contains the token string and metadata. + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTokenObject' + '401': + $ref: '#/components/responses/Unauthorized' + tags: + - Authentication + - Token + /api/v3/configure/enterprise/token/admin/regenerate: + post: + operationId: PostRegenerateAdminToken + summary: Regenerate admin token + description: | + Regenerates an admin token and revokes the previous token with the same name. + + This endpoint is only available in InfluxDB 3 Enterprise. + parameters: [] + responses: + '201': + description: Success. The admin token has been regenerated. + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTokenObject' + '401': + $ref: '#/components/responses/Unauthorized' + tags: + - Authentication + - Token components: parameters: AcceptQueryHeader: @@ -1416,6 +1531,67 @@ components: schema: $ref: '#/components/schemas/QueryRequestObject' schemas: + AdminTokenObject: + type: object + properties: + id: + type: integer + name: + type: string + token: + type: string + hash: + type: string + created_at: + type: string + format: date-time + expiry: + format: date-time + example: + id: 0 + name: _admin + token: apiv3_00xx0Xx0xx00XX0x0 + hash: 00xx0Xx0xx00XX0x0 + created_at: '2025-04-18T14:02:45.331Z' + expiry: null + ResourceTokenObject: + type: object + properties: + token_name: + type: string + permissions: + type: array + items: + type: object + properties: + resource_type: + type: string + enum: + - system + - db + resource_identifier: + type: array + items: + type: string + actions: + type: array + items: + type: string + enum: + - read + - write + expiry_secs: + type: integer + description: The expiration time in seconds. + example: + token_name: All system information + permissions: + - resource_type: system + resource_identifier: + - '*' + actions: + - read + expiry_secs: 300000 ContentEncoding: type: string enum: @@ -1457,13 +1633,10 @@ components: description: | Acknowledges a successful write without waiting for WAL persistence. - #### Data flow in InfluxDB 3 Enterprise + #### Related - 1. **Incoming writes**: The system validates incoming data and stores it in the write buffer (in memory). If the `no_sync` write option is enabled (`no_sync=true`), the server sends a response to acknowledge the write. - 2. **WAL flush**: Every second (default), the system flushes the write buffer to the Write-Ahead Log (WAL) for persistence in the Object store. If `no_sync=false` (default), the server sends a response to acknowledge the write. - 3. **Query availability**: After WAL persistence completes, data moves to the queryable buffer where it becomes available for queries. By default, the server keeps up to 900 WAL files (15 minutes of data) buffered. - 4. **Long-term storage in Parquet**: Every ten minutes (default), the system persists the oldest data from the queryable buffer to the Object store in Parquet format. InfluxDB keeps the remaining data (the most recent 5 minutes) in memory. - 5. **In-memory cache**: InfluxDB puts Parquet files into an in-memory cache so that queries against the most recently persisted data don't have to go to object storage. + - [Use the HTTP API and client libraries to write data](/influxdb3/enterprise/write-data/api-client-libraries/) + - [Data durability](/influxdb3/enterprise/reference/internals/durability/) PrecisionWriteCompatibility: enum: - ms @@ -1782,11 +1955,14 @@ x-tagGroups: tags: - Quick start - Authentication + - Cache data - Common parameters - Response codes - Compatibility endpoints - - Data I/O - - Databases + - Database - Processing engine - Server information - - Tables + - Table + - Token + - Query data + - Write data diff --git a/content/influxdb3/core/admin/tokens/_index.md b/content/influxdb3/core/admin/tokens/_index.md index b5ecc09d7..6ace87894 100644 --- a/content/influxdb3/core/admin/tokens/_index.md +++ b/content/influxdb3/core/admin/tokens/_index.md @@ -1,17 +1,14 @@ --- title: Manage tokens description: > - InfluxDB 3 uses tokens to authenticate and authorize access to resources and data stored in {{< product-name >}}. - Use the `influxdb3` CLI or `/api/v3` HTTP API to manage tokens - for your {{% product-name %}} instance. + Manage tokens to authenticate and authorize access to resources and data in an {{< product-name >}} instance. menu: influxdb3_core: parent: Administer InfluxDB weight: 202 +source: /shared/influxdb3-admin/tokens/_index.md --- -InfluxDB 3 uses tokens to authenticate and authorize access to resources and data stored in {{< product-name >}}. -Use the `influxdb3` CLI or `/api/v3` HTTP API to manage tokens -for your {{% product-name %}} instance. - -{{< children hlevel="h2" readmore=true hr=true >}} +> \ No newline at end of file diff --git a/content/influxdb3/core/admin/tokens/admin/create.md b/content/influxdb3/core/admin/tokens/admin/create.md index 6b2038e36..fe1abbe5e 100644 --- a/content/influxdb3/core/admin/tokens/admin/create.md +++ b/content/influxdb3/core/admin/tokens/admin/create.md @@ -14,6 +14,12 @@ list_code_example: | ```bash influxdb3 create token --admin ``` + #### HTTP API + ```bash + curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' + ``` alt_links: cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/ cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ diff --git a/content/influxdb3/core/reference/internals/authentication.md b/content/influxdb3/core/reference/internals/authentication.md new file mode 100644 index 000000000..8c7a0ae2b --- /dev/null +++ b/content/influxdb3/core/reference/internals/authentication.md @@ -0,0 +1,18 @@ +--- +title: InfluxDB 3 Core authentication and authorization +description: > + {{% product-name %}} uses an Attribute-Based Access Control (ABAC) model to manage permissions + for authentication (authn) and authorization (authz). +menu: + influxdb3_core: + name: Authentication and authorization + parent: Core internals +weight: 107 +related: + - /influxdb3/core/admin/tokens/ +source: /shared/influxdb3-internals-reference/authentication.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/admin/tokens/_index.md b/content/influxdb3/enterprise/admin/tokens/_index.md index 05a33f63c..85bfad732 100644 --- a/content/influxdb3/enterprise/admin/tokens/_index.md +++ b/content/influxdb3/enterprise/admin/tokens/_index.md @@ -1,17 +1,14 @@ --- title: Manage tokens description: > - InfluxDB 3 uses tokens to authenticate and authorize access to resources and data stored in your {{< product-name >}}. - Use the `influxdb3` CLI or `/api/v3` HTTP API to manage tokens - for your {{% product-name %}} instance. + Manage tokens to authenticate and authorize access to resources and data in an {{< product-name >}} instance. menu: influxdb3_enterprise: parent: Administer InfluxDB weight: 202 +source: /shared/influxdb3-admin/tokens/_index.md --- -InfluxDB 3 uses tokens to authenticate and authorize access to resources and data stored in your {{< product-name >}}. -Use the `influxdb3` CLI or `/api/v3` HTTP API to manage tokens -for your {{% product-name %}} instance. - -{{< children hlevel="h2" readmore=true hr=true >}} +> \ No newline at end of file diff --git a/content/influxdb3/enterprise/admin/tokens/admin/create.md b/content/influxdb3/enterprise/admin/tokens/admin/create.md index 3ccbca9e7..c073c622d 100644 --- a/content/influxdb3/enterprise/admin/tokens/admin/create.md +++ b/content/influxdb3/enterprise/admin/tokens/admin/create.md @@ -14,6 +14,12 @@ list_code_example: | ```bash influxdb3 create token --admin ``` + #### HTTP API + ```bash + curl -X POST "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token/admin" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' + ``` alt_links: cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/ cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ diff --git a/content/influxdb3/enterprise/admin/tokens/resource/_index.md b/content/influxdb3/enterprise/admin/tokens/resource/_index.md index 025064604..2d66b6888 100644 --- a/content/influxdb3/enterprise/admin/tokens/resource/_index.md +++ b/content/influxdb3/enterprise/admin/tokens/resource/_index.md @@ -3,7 +3,7 @@ title: Manage resource tokens seotitle: Manage resource tokens in {{< product-name >}} description: > Manage resource tokens in your {{< product-name >}} instance. - Resource tokens grant read and write permissions resources, such as databases + Resource tokens grant fine-grained permissions on resources, such as databases and system information endpoints in your {{< product-name >}} instance. Database resource tokens allow for actions like writing and querying data. menu: @@ -14,8 +14,14 @@ weight: 101 influxdb3/enterprise/tags: [tokens] --- +Manage resource tokens in your {{< product-name >}} instance. +Resource tokens grant fine-grained permissions on resources, such as databases +and system information endpoints in your {{< product-name >}} instance. + +- **Databases**: Database tokens allow for actions like writing and querying data. + +- **System resources**: System information tokens allow read access to server runtime statistics and health. + Access controls for system information API endpoints help prevent information leaks and attacks (such as DoS). + {{< children depth="1" >}} - diff --git a/content/influxdb3/enterprise/admin/tokens/resource/create.md b/content/influxdb3/enterprise/admin/tokens/resource/create.md index 329e12d7e..8e02f185e 100644 --- a/content/influxdb3/enterprise/admin/tokens/resource/create.md +++ b/content/influxdb3/enterprise/admin/tokens/resource/create.md @@ -3,7 +3,7 @@ title: Create a resource token description: > Use the [`influxdb3 create token --permission` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) or the [HTTP API](/influxdb3/enterprise/api/v3/) - to create tokens that grant access to resources such as databases and system information. + to create fine-grained permissions tokens that grant access to resources such as databases and system information. Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance. System tokens allow for reading system information and metrics for your server. menu: @@ -43,7 +43,7 @@ alt_links: Use the [`influxdb3 create token --permission` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) or the [`/api/v3/configure/token` HTTP API endpoint](/influxdb3/enterprise/api/v3/) -to create tokens that grant access to resources such as databases and system information. +to create fine-grained permissions tokens that grant access to resources such as databases and system information. Database tokens allow for reading and writing data in your {{< product-name omit="Clustered" >}} instance. System tokens allow for reading system information and metrics for your server. @@ -73,15 +73,14 @@ The HTTP API examples in this guide use [cURL](https://curl.se/) to send an API Use the [`influxdb3 create token` command](/influxdb3/enterprise/reference/cli/influxdb3/create/token/) -to create a database token with permissions for reading and writing data in +to create a database token with fine-grained permissions for reading and writing data in your {{% product-name %}} instance. -In your terminal, run the `influxdb3 create token` command and provide the following: +In your terminal, run the `influxdb3 create token --permission` command and provide the following: -- `--permission` flag to create a token with permissions -- `--name` flag with a unique description of the token +- `--name`: A unique name for the token - _Options_, for example: - - `--expiry` option with the token expiration time as a duration. + - `--expiry`: The token expiration time as a duration. If an expiration isn't set, the token does not expire until revoked. - Token permissions (read and write) in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example: @@ -89,10 +88,10 @@ In your terminal, run the `influxdb3 create token` command and provide the follo db:DATABASE1,DATABASE2:read,write ``` - - `db:`: The `db` resource type, which specifies the token is for a database. - - `DATABASE1,DATABASE2`: The names of the databases to grant permissions to. + - `db:`: The `db` resource type, which specifies the token is for a database + - `DATABASE1,DATABASE2`: A comma-separated list of database names to grant permissions to. The resource names part supports the `*` wildcard, which grants read or write permissions to all databases. - - `read,write`: The permissions to grant to the token. + - `read,write`: A comma-separated list of permissions to grant to the token. {{% code-placeholders "DATABASE1|DATABASE2|1y" %}} @@ -412,12 +411,12 @@ Use the [`influxdb3 create token` command](/influxdb3/enterprise/reference/cli/i to create a system token with permissions for reading system information from your {{% product-name %}} instance. -In your terminal, run the `influxdb3 create token` command and provide the following: +In your terminal, run the `influxdb3 create token --permission` command and provide the following: - - `--permission` flag to create a token with permissions - - `--name` flag with a unique description of the token + + - `--name`: A unique name for the token - _Options_, for example: - - `--expiry` option with the token expiration time as a duration. + - `--expiry`: The token expiration time as a duration. If an expiration isn't set, the token does not expire until revoked. - Token permissions in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example: diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md index 727a03173..968bbde4c 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token.md @@ -11,5 +11,6 @@ source: /shared/influxdb3-cli/create/token.md --- diff --git a/content/influxdb3/enterprise/reference/internals/authentication.md b/content/influxdb3/enterprise/reference/internals/authentication.md new file mode 100644 index 000000000..95ebeac5a --- /dev/null +++ b/content/influxdb3/enterprise/reference/internals/authentication.md @@ -0,0 +1,18 @@ +--- +title: InfluxDB 3 Enterprise authentication and authorization +description: > + {{% product-name %}} uses an Attribute-Based Access Control (ABAC) model to manage permissions + for authentication (authn) and authorization (authz). +menu: + influxdb3_enterprise: + name: Authentication and authorization + parent: Enterprise internals +weight: 107 +related: + - /influxdb3/enterprise/admin/tokens/ +source: /shared/influxdb3-internals-reference/authentication.md +--- + + \ No newline at end of file diff --git a/content/shared/influxdb3-admin/tokens/_index.md b/content/shared/influxdb3-admin/tokens/_index.md index 8c0d4f906..dd9c51ea4 100644 --- a/content/shared/influxdb3-admin/tokens/_index.md +++ b/content/shared/influxdb3-admin/tokens/_index.md @@ -1,10 +1,4 @@ Manage tokens to authenticate and authorize access to resources and data in your {{< product-name >}} instance. -> [!Note] -> #### Store secure tokens in a secret store -> -> Token strings are returned _only_ on token creation. -> We recommend storing database tokens in a **secure secret store**. - -{{< children hlevel="h2" readmore=true hr=true >}} \ No newline at end of file +{{< children hlevel="h2" readmore=true hr=true >}} diff --git a/content/shared/influxdb3-admin/tokens/admin/_index.md b/content/shared/influxdb3-admin/tokens/admin/_index.md index a98cfeedf..da3e84112 100644 --- a/content/shared/influxdb3-admin/tokens/admin/_index.md +++ b/content/shared/influxdb3-admin/tokens/admin/_index.md @@ -1,6 +1,2 @@ - -Manage admin tokens in your {{< product-name >}} instance. -An admin token grants -access to all actions (CLI commands and API endpoints) for the server. - + {{< children hlevel="h2" readmore=true hr=true >}} \ No newline at end of file diff --git a/content/shared/influxdb3-admin/tokens/admin/create.md b/content/shared/influxdb3-admin/tokens/admin/create.md index f3e77323e..cba3c7def 100644 --- a/content/shared/influxdb3-admin/tokens/admin/create.md +++ b/content/shared/influxdb3-admin/tokens/admin/create.md @@ -9,14 +9,17 @@ An admin token grants full access to all actions for your InfluxDB 3 instance. > > Token strings are returned _only_ on token creation. > We recommend storing database tokens in a **secure secret store**. +> Anyone with access to the admin token has full control over your {{< product-name >}} instance. > If you lose the admin token string, you must regenerate the token. ## Create an admin token -- [Use the influxdb3 CLI](#use-the-influxdb3-cli) -- [Use the HTTP API](#use-the-http-api) - -### Use the influxdb3 CLI +{{< tabs-wrapper >}} +{{% tabs %}} +[CLI](#use-the-influxdb3-cli) +[HTTP API](#use-the-http-api) +{{% /tabs %}} +{{% tab-content %}} Use the `influxdb3 create token --admin` command: @@ -24,10 +27,31 @@ Use the `influxdb3 create token --admin` command: influxdb3 create token --admin ``` -The command returns the token string in plain text. +The output contains the token string in plain text. To use the token as the default for later commands, and to persist the token across sessions, assign the token string to the `INFLUXDB3_AUTH_TOKEN` environment variable. +{{% /tab-content %}} +{{% tab-content %}} +Use the following endpoint to create an admin token: -> [!Caution] -> Protect your admin token. Anyone with access to the admin token has full control over your {{< product-name >}} instance. \ No newline at end of file +{{% show-in "core" %}} +{{% api-endpoint method="POST" endpoint="/api/v3/configure/token/admin" api-ref="/influxdb3/version/api/v3/#operation/PostCreateAdminToken" %}} + +```bash +curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin" \ +--header 'Accept: application/json' \ +--header 'Content-Type: application/json' +``` +{{% /show-in %}} +{{% show-in "enterprise" %}} +{{% api-endpoint method="POST" endpoint="/api/v3/enterprise/configure/token/admin" api-ref="/influxdb3/version/api/v3/#operation/PostCreateAdminToken" %}} + +```bash +curl -X POST "http://{{< influxdb/host >}}/api/v3/{{< product-key >}}/configure/token/admin" \ +--header 'Accept: application/json' \ +--header 'Content-Type: application/json' +``` +{{% /show-in %}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} diff --git a/content/shared/influxdb3-admin/tokens/admin/regenerate.md b/content/shared/influxdb3-admin/tokens/admin/regenerate.md index 4d293076e..8ab8b0b0e 100644 --- a/content/shared/influxdb3-admin/tokens/admin/regenerate.md +++ b/content/shared/influxdb3-admin/tokens/admin/regenerate.md @@ -1,15 +1,95 @@ +Use the `influxdb3` CLI or the HTTP API to regenerate an admin token. +Regenerate a token to rotate it as part of your security practices or if you suspect +the token has been compromised. -## Use the CLI to regenerate an admin token +{{< show-in "enterprise" >}} +Regenerating an admin token deactivates the previous token, +stores the SHA512 hash and metadata of the new token, and returns the new token string. +{{< /show-in >}} +{{< show-in "core" >}} +Regenerating the admin token deactivates the previous token, updates the `_admin` token +SHA512 hash and metadata, and returns the new token string. +{{< /show-in >}} -To regenerate an admin token, you can use the `--regenerate` flag with the `influxdb3 create token --admin` subcommand. This revokes the existing admin token. +An admin token grants access to all actions on the server. +## Prerequisite + +To regenerate a token, you need the current token string. + +## Use the CLI or HTTP API to regenerate an admin token + +> [!Important] +> #### Securely store your token +> +> InfluxDB lets you view the token string only when you create the token. +> Store your token in a secure location, as you cannot retrieve it from the database later. +> InfluxDB 3 stores only the token's hash and metadata in the catalog. + +{{< tabs-wrapper >}} +{{% tabs %}} +[CLI](#cli-regenerate-admin-token) +[HTTP API](#http-api-regenerate-admin-token) +{{% /tabs %}} +{{% tab-content %}} + +Use the `--regenerate` flag with the +`influxdb3 create token --admin` subcommand--for example: + +{{% code-placeholders "ADMIN_TOKEN" %}} ```bash influxdb3 create token --admin \ - --token ADMIN_TOKEN - --host {{< influxdb/host >}} + --token ADMIN_TOKEN \ --regenerate ``` +{{% /code-placeholders %}} -In your command, replace `ADMIN_TOKEN` with the current token string. +In your command, +replace {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}} +with the current token string. -By default, `influxdb3` asks for confirmation before regenerating the token. \ No newline at end of file +The CLI asks for confirmation before regenerating the token. +The output contains the new token string and InfluxDB deactivates the previous token string. + +{{% /tab-content %}} +{{% tab-content %}} + +Use the following HTTP API endpoint: + +{{% show-in "core" %}} +{{% api-endpoint method="POST" endpoint="/api/v3/configure/token/admin/regenerate" api-ref="/influxdb3/version/api/v3/configure/token/admin/regenerate" %}} +{{% /show-in %}} + +{{% show-in "enterprise" %}} +{{% api-endpoint method="POST" endpoint="/api/v3/enterprise/configure/token/admin/regenerate" api-ref="/influxdb3/version/api/v3/enterprise/configure/token/admin" %}} +{{% /show-in %}} + +In your request, send an `Authorization` header with your current admin token string +--for example: + +{{% show-in "core" %}} +{{% code-placeholders "ADMIN_TOKEN" %}} +```bash +curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/token/admin" \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --header "Accept: application/json" +``` +{{% /code-placeholders %}} +{{% /show-in %}} + +{{% show-in "enterprise" %}} +{{% code-placeholders "ADMIN_TOKEN" %}} +```bash +curl -X POST "http://{{< influxdb/host >}}/api/v3/enterprise/configure/token/admin" \ + --header "Authorization: Bearer ADMIN_TOKEN" \ + --header "Accept: application/json" +``` +{{% /code-placeholders %}} +{{% /show-in %}} + +In your command, replace {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}} with the current token string. + +The output contains the new token string and InfluxDB deactivates the previous token string. + +{{% /tab-content %}} +{{< /tabs-wrapper >}} diff --git a/content/shared/influxdb3-internals-reference/authentication.md b/content/shared/influxdb3-internals-reference/authentication.md new file mode 100644 index 000000000..25a70ee84 --- /dev/null +++ b/content/shared/influxdb3-internals-reference/authentication.md @@ -0,0 +1,42 @@ + +{{% product-name %}} uses an Attribute-Based Access Control (ABAC) model to +manage permissions. + +{{% show-in "enterprise" %}} +This model allows for fine-grained control over access to resources and actions +within an {{% product-name %}} instance. +{{% /show-in %}} + +The ABAC model includes the following components: + +- **Authentication (authn)**: The process through which a user verifies their identity. + In {{% product-name %}}, this occurs when a token is validated. + Users may be human or machine (for example, through automation). + {{% product-name %}} tokens represent previously verified authenticated users that facilitate automation. + +- **Authorization (authz)**: The process that determines if an authenticated user can perform a requested action. + In {{% product-name %}}, authorization evaluates whether a token has permissions to perform actions on specific resources. + +- **Context**: The system may use contextual information, such as location or time, + when evaluating permissions. + +- **Subject**: The identity requesting access to the system. + In {{% product-name %}}, the subject is a _token_ (similar to an "API key" in other systems). + Tokens include attributes such as identifier, name, description, and expiration date. + +- **Action**: The operations (for example, CRUD) that subjects may perform on resources. + +- **Permissions**: The set of actions that a specific subject can perform on a specific resource. + Authorization compares the incoming request against the permissions set to decide if the request is allowed or not. + {{% show-in "core" %}} + In {{% product-name %}}, _admin_ tokens have all permissions. + {{% /show-in %}} + {{% show-in "enterprise" %}} + In {{% product-name %}}, _admin_ tokens have all permissions, while _resource_ tokens have specific permissions. + Resource tokens have fine-grained permissions for specific resources of a specific type. + For example, a database token can have permissions to read from a specific database but not write to it. + {{% /show-in %}} + +- **Resource**: The objects that can be accessed or manipulated. + In {{% product-name %}}, resources include databases and system information endpoints. + Resources have attributes such as identifier and name. \ No newline at end of file diff --git a/content/shared/v3-core-get-started/_index.md b/content/shared/v3-core-get-started/_index.md index 46b3511cb..8edb8fa03 100644 --- a/content/shared/v3-core-get-started/_index.md +++ b/content/shared/v3-core-get-started/_index.md @@ -237,17 +237,16 @@ An {{% product-name %}} instance can have one _admin token_, which grants access When you create a token, InfluxDB 3 returns a token string in plain text that you use to authenticate CLI commands and API requests. -Securely store your token, as you won't be able to retrieve it later. To have the `influxdb3` CLI use your admin token automatically, assign it to the `INFLUXDB3_AUTH_TOKEN` environment variable. > [!Important] +> #### Securely store your token > -> #### Securely store your tokens -> -> For security, InfluxDB only lets you view tokens when you create them. -> InfluxDB 3 stores a hash of the token in the catalog, so you can't retrieve the token after it is created. +> InfluxDB lets you view the token string only when you create the token. +> Store your token in a secure location, as you cannot retrieve it from the database later. +> InfluxDB 3 stores only the token's hash and metadata in the catalog. #### Create an admin token @@ -259,9 +258,9 @@ influxdb3 create token --admin \ ``` The command returns a token string that you can use to authenticate CLI commands and API requests. -Securely store your token, as you won't be able to retrieve it later. For more information, see how to [Manage admin tokens](/influxdb3/version/admin/tokens/admin/). + ### Data model The database server contains logical databases, which have tables, which have columns. Compared to previous versions of InfluxDB you can think of a database as a `bucket` in v2 or as a `db/retention_policy` in v1. A `table` is equivalent to a `measurement`, which has columns that can be of type `tag` (a string dictionary), `int64`, `float64`, `uint64`, `bool`, or `string` and finally every table has a `time` column that is a nanosecond precision timestamp. diff --git a/content/shared/v3-enterprise-get-started/_index.md b/content/shared/v3-enterprise-get-started/_index.md index 2eb4ea29b..0922491f0 100644 --- a/content/shared/v3-enterprise-get-started/_index.md +++ b/content/shared/v3-enterprise-get-started/_index.md @@ -262,17 +262,16 @@ You can create multiple resource tokens for different resources. When you create a token, InfluxDB 3 returns a token string in plain text that you use to authenticate CLI commands and API requests. -Securely store your token, as you won't be able to retrieve it later. To have the `influxdb3` CLI use your admin token automatically, assign it to the `INFLUXDB3_AUTH_TOKEN` environment variable. > [!Important] +> #### Securely store your token > -> #### Securely store your tokens -> -> For security, InfluxDB only lets you view tokens when you create them. -> InfluxDB 3 stores a hash of the token in the catalog, so you can't retrieve the token after it is created. +> InfluxDB lets you view the token string only when you create the token. +> Store your token in a secure location, as you cannot retrieve it from the database later. +> InfluxDB 3 stores only the token's hash and metadata in the catalog. #### Create an admin token @@ -284,7 +283,6 @@ influxdb3 create token --admin \ ``` The command returns a token string that you can use to authenticate CLI commands and API requests. -Securely store your token, as you won't be able to retrieve it later. After you have created an admin token, you can use it to create database tokens and system tokens. @@ -294,17 +292,17 @@ For more information, see how to [Manage admin tokens](/influxdb3/version/admin/ To create a database token, use the `influxdb3 create token` subcommand and pass the following: -- `--permission`: Create a token with permissions -- `--name`: A unique description of the token +- `--permission`: Create a token with fine-grained permissions +- `--name`: A unique name for the token - _Options_, for example: - `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#duration). If an expiration isn't set, the token does not expire until revoked. - `--token` option with the admin token to use for authentication - Token permissions as a string literal in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example: - `"db:mydb:read,write"` - - `db:`: The `db` resource type, which specifies the token is for a database. + - `db:`: The `db` resource type, which specifies the token is for a database - `mydb`: The name of the database to grant permissions to. This part supports the `*` wildcard, which grants permissions to all databases. - - `read,write`: The permissions to grant to the token. + - `read,write`: A comma-separated list of permissions to grant to the token. The following example shows how to create a database token that expires in 90 days and has read and write permissions for all databases on the server: @@ -332,8 +330,8 @@ A _system token_ grants read access to system information and metrics for the se - `/ping` To create a system token, use the `influxdb3 create token` subcommand and pass the following: -- `--permission`: Create a token with permissions -- `--name`: A unique description of the token +- `--permission`: Create a token with fine-grained permissions +- `--name`: A unique name for the token - _Options_, for example: - `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#duration). If an expiration isn't set, the token does not expire until revoked.