From fff1693ed3d90f56d49f18691ce2b2ba20974f0a Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 8 Nov 2022 15:36:18 -0600 Subject: [PATCH] chore(api): update to latest openapi: (#4624) - authorizations docs - update Authorizations tag to Authorizations (API tokens) - update link in influxdb/content/v2.5 to match - replace /latest/ with /v2.4/ in latest. --- api-docs/cloud/ref.yml | 540 ++++++++++++++---- api-docs/v2.4/ref.yml | 382 ++++++------- api-docs/v2.5/ref.yml | 289 +++++++--- .../v2.5/security/tokens/view-tokens.md | 2 +- 4 files changed, 838 insertions(+), 375 deletions(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 58f0b02ab..10b53d836 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -377,7 +377,7 @@ components: type: string status: default: active - description: Status of the token. If `inactive`, requests using the token will be rejected. + description: Status of the token. If `inactive`, InfluxDB rejects requests that use the token. enum: - active - inactive @@ -2345,21 +2345,21 @@ components: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - properties: orgID: - description: The ID of the organization that the authorization is scoped to. + description: The organization ID. Identifies the organization that the authorization is scoped to. type: string permissions: description: | - A list of permissions that provide `read` and `write` access to organization resources. + The list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: '#/components/schemas/Permission' minItems: 1 type: array token: - description: A name that you provide for the authorization. + description: The name that you provide for the authorization. type: string userID: - description: The ID of the user that the authorization is scoped to. + description: The user ID. Identifies the user that the authorization is scoped to. type: string type: object required: @@ -3437,6 +3437,24 @@ components: - type - messageTemplate type: object + Params: + properties: + params: + additionalProperties: + enum: + - any + - bool + - duration + - float + - int + - string + - time + - uint + type: string + description: | + The `params` keys and value type defined in the script. + type: object + type: object ParenExpression: description: Represents an expression wrapped in parenthesis properties: @@ -3946,7 +3964,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](/influxdb/cloud/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](/influxdb/cloud/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -4377,11 +4395,10 @@ components: ScriptUpdateRequest: properties: description: - type: string - name: + description: A description of the script. type: string script: - description: script is script to be executed + description: The script to execute. type: string type: object Scripts: @@ -6633,7 +6650,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides @@ -6689,7 +6706,7 @@ paths: Lists authorizations. To limit which authorizations are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all authorizations for the organization. + If no query parameters are passed, InfluxDB returns all authorizations. #### InfluxDB Cloud @@ -6699,7 +6716,11 @@ paths: #### Required permissions + To retrieve an authorization, the request must use an API token that has the + following permissions: + - `read-authorizations` + - `read-user` for the user that the authorization is scoped to #### Related guides @@ -6709,39 +6730,45 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to the specified - [user](/influxdb/cloud/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to the specified - [user](/influxdb/cloud/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). in: query name: user schema: type: string - - description: | - An organization ID. - Only returns authorizations that belong to the specified - [organization](/influxdb/cloud/reference/glossary/#organization). + - description: An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns authorizations that belong to the specified - [organization](/influxdb/cloud/reference/glossary/#organization). + Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). in: query name: org schema: type: string - description: | An API [token](/influxdb/cloud/reference/glossary/#token) value. - Returns the authorization for the specified token. + Specifies an authorization by its `token` property value + and returns the authorization. + + #### InfluxDB OSS + + - Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, + applies other parameters, and then returns the result. + + #### Limitations + + - The parameter is non-repeatable. If you specify more than one, + only the first one is used. If a resource with the specified + property value doesn't exist, then the response body contains an empty list. in: query name: token schema: @@ -6752,7 +6779,19 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorizations' - description: Success. The response body contains a list of authorizations. + description: | + Success. The response body contains a list of authorizations. + + If the response body is missing authorizations that you expect, check that the API + token used in the request has `read-user` permission for the users (`userID` property value) + in those authorizations. + + #### InfluxDB OSS + + - **Warning**: The response body contains authorizations with their + [API token](/influxdb/cloud/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. '400': $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6765,7 +6804,8 @@ paths: description: Unexpected error summary: List authorizations tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints post: description: | Creates an authorization and returns the authorization with the @@ -6773,20 +6813,24 @@ paths: Use this endpoint to create an authorization, which generates an API token with permissions to `read` or `write` to a specific resource or `type` of resource. - - #### Limitations + The API token is the authorization's `token` property value. To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud enforces access restrictions on API tokens. + InfluxDB enforces access restrictions on API tokens. - - InfluxDB only allows access to the API token value immediately after the authorization is created. - - You can't update an authorization's permissions. - - A token stops working when the user who created the authorization is deleted. + - InfluxDB allows access to the API token value immediately after the authorization is created. + - You can’t change access (read/write) permissions for an API token after it’s created. + - Tokens stop working when the user who created the token is deleted. We recommend the following for managing your tokens: - - Create a generic user to create and manage tokens for writing data. - - Store your tokens in a secure password vault for future access. + - Create a generic user to create and manage tokens for writing data. + - Store your tokens in a secure password vault for future access. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to #### Related guides @@ -6815,7 +6859,8 @@ paths: schema: $ref: '#/components/schemas/Authorization' description: | - Success. The authorization is created. The response body contains the authorization. + Success. The authorization is created. The response body contains the + authorization. '400': $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6828,13 +6873,21 @@ paths: description: Unexpected error summary: Create an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/authorizations/{authID}: delete: + description: | + Deletes an authorization. + + Use the endpoint to delete an API token. + + If you want to disable an API token instead of delete it, + [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the authorization to delete. + - description: An authorization ID. Specifies the authorization to delete. in: path name: authID required: true @@ -6842,18 +6895,70 @@ paths: type: string responses: '204': - description: Authorization deleted + description: Success. The authorization is deleted. + '400': + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints get: + description: | + Retrieves an authorization. + + Use this endpoint to retrieve information about an API token, including + the token's permissions and the user that the token is scoped to. + + #### InfluxDB OSS + + - InfluxDB OSS returns + [API token](/influxdb/cloud/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](/influxdb/cloud/security/tokens/view-tokens/) + externalDocs: + description: View tokens + url: https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/ operationId: GetAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the authorization to get. + - description: An authorization ID. Specifies the authorization to retrieve. in: path name: authID required: true @@ -6865,19 +6970,56 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Authorization details + description: Success. The response body contains the authorization. + '400': + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints patch: - description: Update an authorization's status to `active` or `inactive`. + description: | + Updates an authorization. + + Use this endpoint to set an API token's status to be _active_ or _inactive_. + InfluxDB rejects requests that use inactive API tokens. operationId: PatchAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the authorization to update. + - description: An authorization ID. Specifies the authorization to update. in: path name: authID required: true @@ -6888,7 +7030,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: The updated Authorization object. + description: In the request body, provide the authorization properties to update. required: true responses: '200': @@ -6896,13 +7038,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: The updated authorization. + description: Success. The response body contains the updated authorization. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: Update authorization status + summary: Update an API token to be active or inactive tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/buckets: get: description: | @@ -7905,7 +8048,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -7921,7 +8064,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -7986,7 +8129,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8001,7 +8144,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8087,7 +8230,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8103,7 +8246,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8277,6 +8420,7 @@ paths: application/json: schema: $ref: '#/components/schemas/MeasurementSchemaCreateRequest' + required: true responses: '201': content: @@ -8472,6 +8616,7 @@ paths: application/json: schema: $ref: '#/components/schemas/MeasurementSchemaUpdateRequest' + required: true responses: '200': content: @@ -10030,7 +10175,7 @@ paths: 1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve feature flags and their values. - 2. Follow the instructions to [enable, disable, or override values for feature flags](/influxdb/cloud/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](/influxdb/cloud/reference/config-options/#feature-flags). 3. **Optional**: To confirm that your change is applied, do one of the following: - Send a request to this endpoint to retrieve the current feature flag values. @@ -10039,7 +10184,7 @@ paths: #### Related guides - - [InfluxDB configuration options](/influxdb/cloud/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](/influxdb/cloud/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11335,7 +11480,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11433,7 +11578,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11532,7 +11677,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11593,7 +11738,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -11655,7 +11800,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -11665,7 +11810,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: PostOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11739,7 +11884,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11754,7 +11899,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -13775,7 +13920,18 @@ paths: }' /api/v2/scripts/{scriptID}: delete: - description: Deletes a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and all associated records. + description: | + Deletes a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and all associated records. + + #### Limitations + + - You can delete only one script per request. + - If the script ID you provide doesn't exist for the organization, InfluxDB + responds with an HTTP `204` status code. + + #### Related Guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) operationId: DeleteScriptsID parameters: - description: | @@ -13788,7 +13944,9 @@ paths: type: string responses: '204': - description: Success. The script is deleted. + description: | + Success. + The script is queued for deletion. '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -13799,9 +13957,21 @@ paths: summary: Delete a script tags: - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl -X 'DELETE' \ + "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header 'Accept: application/json' get: description: | Retrieves a [script](/influxdb/cloud/api-guide/api-invokable-scripts/). + + #### Related Guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) operationId: GetScriptsID parameters: - description: | @@ -13816,25 +13986,62 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + createdAt: '2022-07-17T23:49:45.731237Z' + description: getLastPoint finds the last point in a bucket + id: 09afa3b220fe4000 + language: flux + name: getLastPoint + orgID: bea7ea952287f70d + script: 'from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)' + updatedAt: '2022-07-17T23:49:45.731237Z' schema: $ref: '#/components/schemas/Script' description: Success. The response body contains the script. '401': $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested script was not found. + value: + code: not found + message: script "09afa3b220fe400" not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/ServerError' - description: Unexpected error. + description: Internal server error. summary: Retrieve a script tags: - Data I/O endpoints - Invokable Scripts patch: description: | - Updates a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and returns the script. + Updates an invokable script. - Use this endpoint to update the properties (`name`, `description`, and `script`) of an invokable script. + Use this endpoint to modify values for script properties (`description` and `script`). + + To update a script, pass an object that contains the updated key-value pairs. + + #### Limitations + + - If you send an empty request body, the script will neither update nor + store an empty script, but InfluxDB will respond with an HTTP `200` status + code. + + #### Related Guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) operationId: PatchScriptsID parameters: - description: | @@ -13850,27 +14057,64 @@ paths: application/json: schema: $ref: '#/components/schemas/ScriptUpdateRequest' - description: The script update to apply. + description: | + An object that contains the updated script properties to apply. required: true responses: '200': content: application/json: + examples: + successResponse: + value: + createdAt: '2022-07-17T23:49:45.731237Z' + description: get last point from new bucket + id: 09afa3b220fe4000 + language: flux + name: getLastPoint + orgID: bea7ea952287f70d + script: 'from(bucket: newBucket) |> range(start: -7d) |> limit(n:1)' + updatedAt: '2022-07-19T22:27:23.185436Z' schema: $ref: '#/components/schemas/Script' description: Success. The response body contains the updated script. - '400': - $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested script wasn't found. + value: + code: not found + message: script "09afa3b220fe400" not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/ServerError' - description: Unexpected error + description: Internal server error summary: Update a script tags: - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl -X 'PATCH' \ + "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header "Accept: application/json" + --header "Content-Type: application/json" + --data '{ + "description": "get last point from new bucket", + "script": "from(bucket: updatedBucket) |> range(start: -7d) |> limit(n:1)", "language": "flux" + }' /api/v2/scripts/{scriptID}/invoke: post: description: | @@ -14117,6 +14361,116 @@ paths: summary: Remove labels from a script tags: - Invokable Scripts + /api/v2/scripts/{scriptID}/params: + get: + description: | + Analyzes a script and determines required parameters. + Find all `params` keys referenced in a script and return a list + of keys. If it is possible to determine the type of the value + from the context then the type is also returned -- for example: + + The following sample script contains a _`mybucket`_ parameter : + + ```json + "script": "from(bucket: params.mybucket) + |> range(start: -7d) + |> limit(n:1)" + ``` + + Requesting the parameters using `GET /api/v2/scripts/SCRIPT_ID/params` + returns the following: + + ```json + { + "params": { + "mybucket": "string" + } + } + ``` + + The type name returned for a parameter will be one of: + + - `any` + - `bool` + - `duration` + - `float` + - `int` + - `string` + - `time` + - `uint` + + The type name `any` is used when the type of a parameter cannot + be determined from the context, or the type is determined to + be a structured type such as an array or record. + + #### Related guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + operationId: GetScriptsIDParams + parameters: + - description: | + A script ID. + The script to analyze for params. + in: path + name: scriptID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + params: + mybucket: string + schema: + $ref: '#/components/schemas/Params' + description: | + Success. + The response body contains the parameters found, along with their types. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + scriptNotFound: + description: InfluxDB can't find the requested script. + summary: | + Script not found + value: + code: not found + message: script "09afa3b220fe400" not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: not found + type: string + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error. + summary: Find script parameters. + tags: + - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request GET "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/params" \ + --header "Authorization: Token INFLUX_TOKEN" /api/v2/setup: get: description: Check if setup is allowed. Returns `true` if no default user, organization, or bucket have been created. @@ -15260,7 +15614,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](/influxdb/cloud/reference/glossary/#task). operationId: GetTasksIDMembers @@ -15298,7 +15652,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task](/influxdb/cloud/reference/glossary/#task) and then returns the member. @@ -15345,7 +15699,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](/influxdb/cloud/reference/glossary/#task). operationId: DeleteTasksIDMembersID @@ -15380,7 +15734,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. operationId: GetTasksIDOwners @@ -15432,7 +15786,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. @@ -15509,7 +15863,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task](/influxdb/cloud/reference/glossary/#task). operationId: DeleteTasksIDOwnersID @@ -18274,24 +18628,12 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. - In InfluxDB Cloud, an authorization with `read-authorizations` permission - can be used to view other authorizations. - - #### Limitations - - To follow best practices for secure API token generation and retrieval, - InfluxDB enforces access restrictions on API tokens. - - - InfluxDB allows access to the API token value immediately after the authorization is created. - - You can’t change access (read/write) permissions for an API token after it’s created. - - Tokens stop working when the user who created the token is deleted. - We recommend the following for managing your tokens: - Create a generic user to create and manage tokens for writing data. - Store your tokens in a secure password vault for future access. - #### User sessions with authorizations + ### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If the user signs in with username and password, creating a _user session_, @@ -18309,7 +18651,7 @@ tags: - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication) - [Manage API tokens](/influxdb/cloud/security/tokens/) - [Assign a token to a specific user](/influxdb/cloud/security/tokens/create-token/) - name: Authorizations + name: Authorizations (API tokens) - name: Bucket Schemas - description: | Store your data in InfluxDB [buckets](/influxdb/cloud/reference/glossary/#bucket). @@ -18378,7 +18720,7 @@ tags: Use the `/api/v2/scripts` endpoints to create and manage scripts. See related guides to learn how to define parameters and execute scripts. - #### Related guides + ### Related guides - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -18407,7 +18749,7 @@ tags: | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). | | `after` | string (resource ID) | Only returns resources created after the specified resource. | - #### Limitations + ### Limitations - For specific endpoint parameters and examples, see the endpoint definition. - If you specify an `offset` parameter value greater than the total number of records, @@ -18492,7 +18834,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -18500,7 +18842,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks](/influxdb/cloud/process-data/get-started/) - [Common data processing tasks](/influxdb/cloud/process-data/common-tasks/) @@ -18525,7 +18867,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](/influxdb/cloud/influxdb-templates/) @@ -18541,14 +18883,14 @@ tags: `GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to view specific members. - #### User sessions with authorizations + ### User sessions with authorizations Optionally, you can scope an authorization (and its API token) to a user. If a user signs in with username and password, creating a _user session_, the session carries the permissions granted by all the user's authorizations. To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). - #### Related guides + ### Related guides - [Manage users](/influxdb/cloud/organizations/users/) name: Users @@ -18573,7 +18915,7 @@ x-tagGroups: - System information endpoints - name: All endpoints tags: - - Authorizations + - Authorizations (API tokens) - Bucket Schemas - Buckets - Cells diff --git a/api-docs/v2.4/ref.yml b/api-docs/v2.4/ref.yml index 934cb9426..a19afcb24 100644 --- a/api-docs/v2.4/ref.yml +++ b/api-docs/v2.4/ref.yml @@ -7,7 +7,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](/influxdb/latest/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](/influxdb/v2.4/api/#tag/Pagination). in: query name: after required: false @@ -36,7 +36,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](/influxdb/latest/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](/influxdb/v2.4/api/#tag/Pagination). in: query name: offset required: false @@ -777,7 +777,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -1216,7 +1216,7 @@ components: $ref: '#/components/schemas/Links' type: object DateTimeLiteral: - description: Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](/influxdb/latest/reference/glossary/#rfc3339nano-timestamp). + description: Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](/influxdb/v2.4/reference/glossary/#rfc3339nano-timestamp). properties: type: $ref: '#/components/schemas/NodeType' @@ -1281,18 +1281,18 @@ components: properties: predicate: description: | - An expression in [delete predicate syntax](/influxdb/latest/reference/syntax/delete-predicate/). + An expression in [delete predicate syntax](/influxdb/v2.4/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string start: description: | - A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. format: date-time type: string stop: description: | - A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. format: date-time type: string @@ -1303,7 +1303,7 @@ components: Dialect: description: | Options for tabular data output. - Default output is [annotated CSV](/influxdb/latest/reference/syntax/annotated-csv/#csv-response-format) with headers. + Default output is [annotated CSV](/influxdb/v2.4/reference/syntax/annotated-csv/#csv-response-format) with headers. For more information about tabular data **dialect**, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). @@ -1315,7 +1315,7 @@ components: #### Related guides - - See [Annotated CSV annotations](/influxdb/latest/reference/syntax/annotated-csv/#annotations) for examples and more information. + - See [Annotated CSV annotations](/influxdb/v2.4/reference/syntax/annotated-csv/#annotations) for examples and more information. For more information about **annotations** in tabular data, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). @@ -1337,7 +1337,7 @@ components: default: RFC3339 description: | The format for timestamps in results. - Default is [`RFC3339` date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp). + Default is [`RFC3339` date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values @@ -2522,7 +2522,7 @@ components: readOnly: true type: string time: - description: The time ([RFC3339Nano date/time format](/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. + description: The time ([RFC3339Nano date/time format](/influxdb/v2.4/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true @@ -2861,7 +2861,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -3207,7 +3207,7 @@ components: type: integer shardGroupDurationSeconds: description: | - The [shard group duration](/influxdb/latest/reference/glossary/#shard). + The [shard group duration](/influxdb/v2.4/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud @@ -3216,11 +3216,11 @@ components: #### InfluxDB OSS - - Default value depends on the [bucket retention period](/influxdb/latest/reference/internals/shards/#shard-group-duration). + - Default value depends on the [bucket retention period](/influxdb/v2.4/reference/internals/shards/#shard-group-duration). #### Related guides - - InfluxDB [shards and shard groups](/influxdb/latest/reference/internals/shards/) + - InfluxDB [shards and shard groups](/influxdb/v2.4/reference/internals/shards/) format: int64 type: integer type: @@ -3346,7 +3346,7 @@ components: [Retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is - [retention period](/influxdb/latest/reference/glossary/#retention-period). + [retention period](/influxdb/v2.4/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. type: string schemaType: @@ -3876,7 +3876,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](/influxdb/v2.4/v2.3/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -3890,7 +3890,7 @@ components: RetentionRules: description: | Retention rules to expire or retain data. - The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/latest/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/v2.4/reference/glossary/#retention-period). #### InfluxDB Cloud @@ -4039,13 +4039,13 @@ components: readOnly: true type: array requestedAt: - description: The time ([RFC3339Nano date/time format](/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. + description: The time ([RFC3339Nano date/time format](/influxdb/v2.4/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true type: string scheduledFor: - description: The time [RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. + description: The time [RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. format: date-time type: string startedAt: @@ -4070,7 +4070,7 @@ components: properties: scheduledFor: description: | - The time [RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp) + The time [RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. format: date-time @@ -4782,7 +4782,7 @@ components: description: A description of the task. type: string every: - description: The interval ([duration literal](/influxdb/latest/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. + description: The interval ([duration literal](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. format: duration type: string flux: @@ -4805,7 +4805,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -4841,17 +4841,17 @@ components: type: string org: description: | - An [organization](/influxdb/latest/reference/glossary/#organization) name. + An [organization](/influxdb/v2.4/reference/glossary/#organization) name. Specifies the organization that owns the task. type: string orgID: description: | - An [organization](/influxdb/latest/reference/glossary/#organization) ID. + An [organization](/influxdb/v2.4/reference/glossary/#organization) ID. Specifies the organization that owns the task. type: string ownerID: description: | - A [user](/influxdb/latest/reference/glossary/#user) ID. + A [user](/influxdb/v2.4/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the @@ -5203,7 +5203,7 @@ components: When you apply a template, InfluxDB replaces `envRef` objects in the template with the values that you provide in the `envRefs` parameter. - For more examples, see how to [define environment references](/influxdb/latest/influxdb-templates/use/#define-environment-references). + For more examples, see how to [define environment references](/influxdb/v2.4/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -5212,7 +5212,7 @@ components: - `spec.associations.name` For more information about including environment references in template fields, see how to - [include user-definable resource names](/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names). + [include user-definable resource names](/influxdb/v2.4/influxdb-templates/create/#include-user-definable-resource-names). type: object orgID: description: | @@ -5221,7 +5221,7 @@ components: The organization owns all resources created by the template. To find your organization, see how to - [view organizations](/influxdb/latest/organizations/view-orgs/). + [view organizations](/influxdb/v2.4/organizations/view-orgs/). type: string remotes: description: | @@ -5282,7 +5282,7 @@ components: #### Related guides - - [How to pass secrets when installing a template](/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](/influxdb/v2.4/influxdb-templates/use/#pass-secrets-when-installing-a-template) type: object stackID: description: | @@ -5296,8 +5296,8 @@ components: #### Related guides - - [Stacks](/influxdb/latest/influxdb-templates/stacks/) - - [View stacks](/influxdb/latest/influxdb-templates/stacks/view/) + - [Stacks](/influxdb/v2.4/influxdb-templates/stacks/) + - [View stacks](/influxdb/v2.4/influxdb-templates/stacks/view/) type: string template: description: | @@ -6546,8 +6546,8 @@ components: For more information and examples, see the following: - [`/authorizations`(#tag/Authorizations) endpoints] - - [Authorize API requests](/influxdb/latest/api-guide/api_intro/#authentication) - - [Manage API tokens](/influxdb/latest/security/tokens/) + - [Authorize API requests](/influxdb/v2.4/api-guide/api_intro/#authentication) + - [Manage API tokens](/influxdb/v2.4/security/tokens/) in: header name: Authorization type: apiKey @@ -6599,42 +6599,42 @@ paths: #### InfluxDB OSS - Returns - [API token](/influxdb/latest/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, + [API token](/influxdb/v2.4/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](/influxdb/v2.4/security/tokens/#operator-token)_, InfluxDB OSS returns authorizations for all organizations in the instance. #### Required permissions - - InfluxDB OSS requires an _[operator token](/influxdb/latest/security/tokens/#operator-token)_. + - InfluxDB OSS requires an _[operator token](/influxdb/v2.4/security/tokens/#operator-token)_. #### Related guides - - [View tokens](/influxdb/latest/security/tokens/view-tokens/) + - [View tokens](/influxdb/v2.4/security/tokens/view-tokens/) operationId: GetAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to the specified [user](/influxdb/latest/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](/influxdb/v2.4/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to the specified [user](/influxdb/latest/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](/influxdb/v2.4/reference/glossary/#user). in: query name: user schema: type: string - - description: An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/latest/reference/glossary/#organization). + - description: An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/v2.4/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns authorizations that belong to the specified [organization](/influxdb/latest/reference/glossary/#organization). + Only returns authorizations that belong to the specified [organization](/influxdb/v2.4/reference/glossary/#organization). in: query name: org schema: @@ -6677,7 +6677,7 @@ paths: #### Limitations - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any - user with an _[operator token](/influxdb/latest/security/tokens/#operator-token)_. + user with an _[operator token](/influxdb/v2.4/security/tokens/#operator-token)_. - Even if an API token has `read-authorizations` permission, the token can't be used to view its authorization details. - Tokens stop working when the user who created the token is deleted. @@ -6686,7 +6686,7 @@ paths: #### Related guides - - [Create a token](/influxdb/latest/security/tokens/create-token/) + - [Create a token](/influxdb/v2.4/security/tokens/create-token/) operationId: PostAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' @@ -6910,7 +6910,7 @@ paths: schema: format: int64 type: integer - - description: The earliest time [RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp) to include in the snapshot. + - description: The earliest time [RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp) to include in the snapshot. examples: RFC3339: summary: RFC3339 date/time format @@ -6954,12 +6954,12 @@ paths: /api/v2/buckets: get: description: | - Retrieves a list of [buckets](/influxdb/latest/reference/glossary/#bucket). + Retrieves a list of [buckets](/influxdb/v2.4/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the - [organization](/influxdb/latest/reference/glossary/#organization) + [organization](/influxdb/v2.4/reference/glossary/#organization) associated with the authorization - ([API token](/influxdb/latest/reference/glossary/#token)). + ([API token](/influxdb/v2.4/reference/glossary/#token)). To limit which buckets are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all buckets up to the default `limit`. @@ -6970,7 +6970,7 @@ paths: #### InfluxDB OSS - - If you use an _[operator token](/influxdb/latest/security/tokens/#operator-token)_ + - If you use an _[operator token](/influxdb/v2.4/security/tokens/#operator-token)_ to authenticate your request, InfluxDB retrieves resources for _all organizations_ in the instance. To retrieve resources for only a specific organization, use the @@ -6981,11 +6981,11 @@ paths: | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | + | Retrieve [_system buckets_](/influxdb/v2.4/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - - [Manage buckets](/influxdb/latest/organizations/buckets/) + - [Manage buckets](/influxdb/v2.4/organizations/buckets/) operationId: GetBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7085,10 +7085,10 @@ paths: --header "Content-Type: application/json" post: description: | - Creates a [bucket](/influxdb/latest/reference/glossary/#bucket) + Creates a [bucket](/influxdb/v2.4/reference/glossary/#bucket) and returns the bucket resource. The default data - [retention period](/influxdb/latest/reference/glossary/#retention-period) + [retention period](/influxdb/v2.4/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS @@ -7107,8 +7107,8 @@ paths: #### Related Guides - - [Create a bucket](/influxdb/latest/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](/influxdb/latest/reference/cli/influx/bucket/create) + - [Create a bucket](/influxdb/v2.4/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](/influxdb/v2.4/reference/cli/influx/bucket/create) operationId: PostBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7245,7 +7245,7 @@ paths: #### Related Guides - - [Delete a bucket](/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](/influxdb/v2.4/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) operationId: DeleteBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7408,7 +7408,7 @@ paths: #### Related Guides - - [Update a bucket](/influxdb/latest/organizations/buckets/update-bucket/) + - [Update a bucket](/influxdb/v2.4/organizations/buckets/update-bucket/) operationId: PatchBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7546,7 +7546,7 @@ paths: #### Related guides - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. - - [Manage labels in the InfluxDB UI](/influxdb/latest/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](/influxdb/v2.4/visualize-data/labels/) operationId: GetBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7610,7 +7610,7 @@ paths: #### Related guides - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. - - [Manage labels in the InfluxDB UI](/influxdb/latest/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](/influxdb/v2.4/visualize-data/labels/) operationId: PostBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7736,18 +7736,18 @@ paths: description: | Retrieves a list of all users for a bucket. - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have + InfluxDB [users](/influxdb/v2.4/reference/glossary/#user) have permission to access InfluxDB. - [Members](/influxdb/latest/reference/glossary/#member) are users in + [Members](/influxdb/v2.4/reference/glossary/#member) are users in an organization with access to the specified resource. Use this endpoint to retrieve all users with access to a bucket. #### Related guides - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) + - [Manage users](/influxdb/v2.4/users/) + - [Manage members](/influxdb/v2.4/organizations/members/) operationId: GetBucketsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7806,18 +7806,18 @@ paths: description: | Add a user to a bucket and return the new user information. - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have + InfluxDB [users](/influxdb/v2.4/reference/glossary/#user) have permission to access InfluxDB. - [Members](/influxdb/latest/reference/glossary/#member) are users in + [Members](/influxdb/v2.4/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) + - [Manage users](/influxdb/v2.4/users/) + - [Manage members](/influxdb/v2.4/organizations/members/) operationId: PostBucketsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7897,8 +7897,8 @@ paths: #### Related guides - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) + - [Manage users](/influxdb/v2.4/users/) + - [Manage members](/influxdb/v2.4/organizations/members/) operationId: DeleteBucketsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7939,7 +7939,7 @@ paths: /api/v2/buckets/{bucketID}/owners: get: description: | - Retrieves a list of all [owners](/influxdb/latest/reference/glossary/#owner) + Retrieves a list of all [owners](/influxdb/v2.4/reference/glossary/#owner) for a bucket. Bucket owners have permission to delete buckets and remove user and member @@ -7968,7 +7968,7 @@ paths: #### Related guides - - [Manage users](/influxdb/latest/users/) + - [Manage users](/influxdb/v2.4/users/) operationId: GetBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8019,7 +8019,7 @@ paths: - Buckets post: description: | - Adds an owner to a bucket and returns the [owners](/influxdb/latest/reference/glossary/#owner) + Adds an owner to a bucket and returns the [owners](/influxdb/v2.4/reference/glossary/#owner) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. @@ -8047,7 +8047,7 @@ paths: #### Related guides - - [Manage users](/influxdb/latest/users/) + - [Manage users](/influxdb/v2.4/users/) operationId: PostBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8148,7 +8148,7 @@ paths: #### Related guides - - [Manage users](/influxdb/latest/users/) + - [Manage users](/influxdb/v2.4/users/) operationId: DeleteBucketsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8517,7 +8517,7 @@ paths: #### Related guides - - [View your runtime server configuration](/influxdb/latest/reference/config-options/#view-your-runtime-server-configuration) + - [View your runtime server configuration](/influxdb/v2.4/reference/config-options/#view-your-runtime-server-configuration) operationId: GetConfig parameters: - $ref: '#/components/parameters/TraceSpan' @@ -9505,7 +9505,7 @@ paths: - **allocs**: All past memory allocations - **block**: Stack traces that led to blocking on synchronization primitives - **cpu**: (Optional) Program counters sampled from the executing stack. - Include by passing the `cpu` query parameter with a [duration](/influxdb/latest/reference/glossary/#duration) value. + Include by passing the `cpu` query parameter with a [duration](/influxdb/v2.4/reference/glossary/#duration) value. Equivalent to the report from [`GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS`](#operation/GetDebugPprofProfile). - **goroutine**: All current goroutines - **heap**: Memory allocations for live objects @@ -9515,13 +9515,13 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - Collects and returns CPU profiling data for the specified [duration](/influxdb/latest/reference/glossary/#duration). + Collects and returns CPU profiling data for the specified [duration](/influxdb/v2.4/reference/glossary/#duration). in: query name: cpu schema: externalDocs: description: InfluxDB duration - url: https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration + url: https://docs.influxdata.com/influxdb/v2.4/reference/glossary/#duration format: duration type: string responses: @@ -10256,8 +10256,8 @@ paths: #### Related guides - - [Delete data](/influxdb/latest/write-data/delete-data/) - - Learn how to use [delete predicate syntax](/influxdb/latest/reference/syntax/delete-predicate/). + - [Delete data](/influxdb/v2.4/write-data/delete-data/) + - Learn how to use [delete predicate syntax](/influxdb/v2.4/reference/syntax/delete-predicate/). - Learn how InfluxDB handles [deleted tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). operationId: PostDelete @@ -10328,8 +10328,8 @@ paths: #### Related guides - - [Delete data](/influxdb/latest/write-data/delete-data/) - - Learn how to use [delete predicate syntax](/influxdb/latest/reference/syntax/delete-predicate/). + - [Delete data](/influxdb/v2.4/write-data/delete-data/) + - Learn how to use [delete predicate syntax](/influxdb/v2.4/reference/syntax/delete-predicate/). required: true responses: '204': @@ -10615,7 +10615,7 @@ paths: /api/v2/me/password: put: description: | - Updates the password for the signed-in [user](/influxdb/latest/reference/glossary/#user). + Updates the password for the signed-in [user](/influxdb/v2.4/reference/glossary/#user). This endpoint represents the third step in the following three-step process to let a user with a user session update their password: @@ -10641,13 +10641,13 @@ paths: #### Related guides - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) - - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) + - [InfluxDB OSS - Change your password](/influxdb/v2.4/users/change-password/) operationId: PutMePassword parameters: - $ref: '#/components/parameters/TraceSpan' - description: | The user session cookie for the - [user](/influxdb/latest/reference/glossary/#user) + [user](/influxdb/v2.4/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides @@ -10702,9 +10702,9 @@ paths: #### Related guides - - For the list of metrics categories, see [InfluxDB OSS metrics](/influxdb/latest/reference/internals/metrics/). - - Learn how to use InfluxDB to [scrape Prometheus metrics](/influxdb/latest/write-data/developer-tools/scrape-prometheus-metrics/). - - Learn how InfluxDB [parses the Prometheus exposition format](/influxdb/latest/reference/prometheus-metrics/). + - For the list of metrics categories, see [InfluxDB OSS metrics](/influxdb/v2.4/reference/internals/metrics/). + - Learn how to use InfluxDB to [scrape Prometheus metrics](/influxdb/v2.4/write-data/developer-tools/scrape-prometheus-metrics/). + - Learn how InfluxDB [parses the Prometheus exposition format](/influxdb/v2.4/reference/prometheus-metrics/). operationId: GetMetrics parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11365,7 +11365,7 @@ paths: /api/v2/orgs: get: description: | - Retrieves a list of [organizations](/influxdb/latest/reference/glossary/#organization/). + Retrieves a list of [organizations](/influxdb/v2.4/reference/glossary/#organization/). To limit which organizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. @@ -11376,7 +11376,7 @@ paths: #### Related guides - - [View organizations](/influxdb/latest/organizations/view-orgs/) + - [View organizations](/influxdb/v2.4/organizations/view-orgs/) operationId: GetOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11448,7 +11448,7 @@ paths: - Security and access endpoints post: description: | - Creates an [organization](/influxdb/latest/reference/glossary/#organization) + Creates an [organization](/influxdb/v2.4/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud @@ -11457,7 +11457,7 @@ paths: #### Related guides - - [Manage organizations](/influxdb/latest/organizations) + - [Manage organizations](/influxdb/v2.4/organizations) operationId: PostOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11555,7 +11555,7 @@ paths: #### Related guides - - [Delete organizations](/influxdb/latest/organizations/delete-orgs/) + - [Delete organizations](/influxdb/v2.4/organizations/delete-orgs/) operationId: DeleteOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11614,7 +11614,7 @@ paths: #### Related guides - - [View organizations](/influxdb/latest/organizations/view-orgs/) + - [View organizations](/influxdb/v2.4/organizations/view-orgs/) operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11684,7 +11684,7 @@ paths: #### Related Guides - - [Update an organization](/influxdb/latest/organizations/update-org/) + - [Update an organization](/influxdb/v2.4/organizations/update-org/) operationId: PatchOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11731,10 +11731,10 @@ paths: description: | Retrieves a list of all users that belong to an organization. - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have + InfluxDB [users](/influxdb/v2.4/reference/glossary/#user) have permission to access InfluxDB. - [Members](/influxdb/latest/reference/glossary/#member) are users + [Members](/influxdb/v2.4/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -11756,8 +11756,8 @@ paths: #### Related guides - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) + - [Manage users](/influxdb/v2.4/users/) + - [Manage members](/influxdb/v2.4/organizations/members/) operationId: GetOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11830,10 +11830,10 @@ paths: description: | Add a user to an organization. - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have + InfluxDB [users](/influxdb/v2.4/reference/glossary/#user) have permission to access InfluxDB. - [Members](/influxdb/latest/reference/glossary/#member) are users + [Members](/influxdb/v2.4/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -11853,8 +11853,8 @@ paths: #### Related guides - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) + - [Manage users](/influxdb/v2.4/users/) + - [Manage members](/influxdb/v2.4/organizations/members/) operationId: PostOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11952,7 +11952,7 @@ paths: #### Related guides - - [Manage members](/influxdb/latest/organizations/members/) + - [Manage members](/influxdb/v2.4/organizations/members/) operationId: DeleteOrgsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12135,7 +12135,7 @@ paths: /api/v2/orgs/{orgID}/owners/{userID}: delete: description: | - Removes an [owner](/influxdb/latest/reference/glossary/#owner) from + Removes an [owner](/influxdb/v2.4/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member @@ -12326,7 +12326,7 @@ paths: #### Related guides - - [Influx ping](/influxdb/latest/reference/cli/influx/ping/) + - [Influx ping](/influxdb/v2.4/reference/cli/influx/ping/) operationId: GetPing responses: '204': @@ -12370,7 +12370,7 @@ paths: #### Related guides - - [Influx ping](/influxdb/latest/reference/cli/influx/ping/) + - [Influx ping](/influxdb/v2.4/reference/cli/influx/ping/) operationId: HeadPing responses: '204': @@ -12413,7 +12413,7 @@ paths: #### Related guides - - [Query with the InfluxDB API](/influxdb/latest/query-data/execute-queries/influx-api/) + - [Query with the InfluxDB API](/influxdb/v2.4/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) operationId: PostQuery parameters: @@ -12532,9 +12532,9 @@ paths: description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](/influxdb/latest/account-management/limits/#adjustable-service-quotas) + plan's [adjustable service quotas](/influxdb/v2.4/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum - [global limit](/influxdb/latest/account-management/limits/#global-limits) + [global limit](/influxdb/v2.4/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: @@ -12718,7 +12718,7 @@ paths: post: description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) + Tree (AST)](/influxdb/v2.4/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query @@ -13184,7 +13184,7 @@ paths: #### Related Guides - - [List of all Flux functions](/influxdb/latest/flux/v0.x/stdlib/all-functions/) + - [List of all Flux functions](/influxdb/v2.4/flux/v0.x/stdlib/all-functions/) operationId: GetQuerySuggestions parameters: - $ref: '#/components/parameters/TraceSpan' @@ -13837,7 +13837,7 @@ paths: #### Related Guides - - [List of all Flux functions](/influxdb/latest/flux/v0.x/stdlib/all-functions/) + - [List of all Flux functions](/influxdb/v2.4/flux/v0.x/stdlib/all-functions/) operationId: GetQuerySuggestionsName parameters: - $ref: '#/components/parameters/TraceSpan' @@ -14906,7 +14906,7 @@ paths: post: description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](/influxdb/latest/reference/glossary/#user), + for a [user](/influxdb/v2.4/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the @@ -15356,8 +15356,8 @@ paths: #### Related guides - - [InfluxDB stacks](/influxdb/latest/influxdb-templates/stacks/) - - [Use InfluxDB templates](/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance) + - [InfluxDB stacks](/influxdb/v2.4/influxdb-templates/stacks/) + - [Use InfluxDB templates](/influxdb/v2.4/influxdb-templates/use/#apply-templates-to-an-influxdb-instance) operationId: CreateStack requestBody: content: @@ -15551,19 +15551,19 @@ paths: /api/v2/tasks: get: description: | - Retrieves a list of [tasks](/influxdb/latest/reference/glossary/#task). + Retrieves a list of [tasks](/influxdb/v2.4/reference/glossary/#task). To limit which tasks are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. #### Related guide - - [Process data with InfluxDB tasks](/influxdb/latest/process-data/) + - [Process data with InfluxDB tasks](/influxdb/v2.4/process-data/) operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](/influxdb/latest/reference/glossary/#task) name. + A [task](/influxdb/v2.4/reference/glossary/#task) name. Only returns tasks with the specified name. Different tasks may have the same name. in: query @@ -15571,35 +15571,35 @@ paths: schema: type: string - description: | - A [task](/influxdb/latest/reference/glossary/#task) ID. + A [task](/influxdb/v2.4/reference/glossary/#task) ID. Only returns tasks created after the specified task. in: query name: after schema: type: string - description: | - A [user](/influxdb/latest/reference/glossary/#user) ID. + A [user](/influxdb/v2.4/reference/glossary/#user) ID. Only returns tasks owned by the specified user. in: query name: user schema: type: string - description: | - An [organization](/influxdb/latest/reference/glossary/#organization) name. + An [organization](/influxdb/v2.4/reference/glossary/#organization) name. Only returns tasks owned by the specified organization. in: query name: org schema: type: string - description: | - An [organization](/influxdb/latest/reference/glossary/#organization) ID. + An [organization](/influxdb/v2.4/reference/glossary/#organization) ID. Only returns tasks owned by the specified organization. in: query name: orgID schema: type: string - description: | - A [task](/influxdb/latest/reference/glossary/#task) status. + A [task](/influxdb/v2.4/reference/glossary/#task) status. Only returns tasks that have the specified status (`active` or `inactive`). in: query name: status @@ -15609,7 +15609,7 @@ paths: - inactive type: string - description: | - The maximum number of [tasks](/influxdb/latest/reference/glossary/#task) to return. + The maximum number of [tasks](/influxdb/v2.4/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. @@ -15623,7 +15623,7 @@ paths: minimum: 1 type: integer - description: | - A [task](/influxdb/latest/reference/glossary/#task) type (`basic` or `system`). + A [task](/influxdb/v2.4/reference/glossary/#task) type (`basic` or `system`). Default is `system`. Specifies the level of detail for tasks in the response. The default (`system`) response contains all the metadata properties for tasks. @@ -15730,14 +15730,14 @@ paths: --header 'Authorization: Token INFLUX_API_TOKEN' post: description: | - Creates a [task](/influxdb/latest/reference/glossary/#task) and returns the task. + Creates a [task](/influxdb/v2.4/reference/glossary/#task) and returns the task. #### Related guides - - [Get started with tasks](/influxdb/latest/process-data/get-started/) - - [Create a task](/influxdb/latest/process-data/manage-tasks/create-task/) - - [Common tasks](/influxdb/latest/process-data/common-tasks/) - - [Task configuration options](/influxdb/latest/process-data/task-options/) + - [Get started with tasks](/influxdb/v2.4/process-data/get-started/) + - [Create a task](/influxdb/v2.4/process-data/manage-tasks/create-task/) + - [Common tasks](/influxdb/v2.4/process-data/common-tasks/) + - [Task configuration options](/influxdb/v2.4/process-data/task-options/) operationId: PostTasks parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15846,7 +15846,7 @@ paths: - Tasks get: description: | - Retrieves a [task](/influxdb/latest/reference/glossary/#task). + Retrieves a [task](/influxdb/v2.4/reference/glossary/#task). operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16037,7 +16037,7 @@ paths: /api/v2/tasks/{taskID}/logs: get: description: | - Retrieves a list of all logs for a [task](/influxdb/latest/reference/glossary/#task). + Retrieves a list of all logs for a [task](/influxdb/v2.4/reference/glossary/#task). When an InfluxDB task runs, a “run” record is created in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. @@ -16366,7 +16366,7 @@ paths: /api/v2/tasks/{taskID}/runs: get: description: | - Retrieves a list of runs for a [task](/influxdb/latest/process-data/). + Retrieves a list of runs for a [task](/influxdb/v2.4/process-data/). To limit which task runs are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. @@ -16396,7 +16396,7 @@ paths: minimum: 1 type: integer - description: | - A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after this time. in: query name: afterTime @@ -16404,7 +16404,7 @@ paths: format: date-time type: string - description: | - A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before this time. in: query name: beforeTime @@ -16470,7 +16470,7 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}: delete: description: | - Cancels a running [task](/influxdb/latest/reference/glossary/#task). + Cancels a running [task](/influxdb/v2.4/reference/glossary/#task). Use this endpoint with InfluxDB OSS to cancel a running task. @@ -16531,7 +16531,7 @@ paths: - Tasks get: description: | - Retrieves a specific run for a [task](/influxdb/latest/reference/glossary/#task). + Retrieves a specific run for a [task](/influxdb/v2.4/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. operationId: GetTasksIDRunsID @@ -16664,7 +16664,7 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}/retry: post: description: | - Queues a [task](/influxdb/latest/reference/glossary/#task) run to + Queues a [task](/influxdb/v2.4/reference/glossary/#task) run to retry and returns the scheduled run. To manually start a _new_ task run, use the @@ -16677,7 +16677,7 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](/influxdb/latest/reference/glossary/#task) ID. + A [task](/influxdb/v2.4/reference/glossary/#task) ID. Specifies the task to retry. in: path name: taskID @@ -16685,7 +16685,7 @@ paths: schema: type: string - description: | - A [task](/influxdb/latest/reference/glossary/#task) run ID. + A [task](/influxdb/v2.4/reference/glossary/#task) run ID. Specifies the task run to retry. To find a task run ID, use the @@ -17211,8 +17211,8 @@ paths: post: description: | Applies a template to - create or update a [stack](/influxdb/latest/influxdb-templates/stacks/) of InfluxDB - [resources](/influxdb/latest/reference/cli/influx/export/all/#resources). + create or update a [stack](/influxdb/v2.4/influxdb-templates/stacks/) of InfluxDB + [resources](/influxdb/v2.4/reference/cli/influx/export/all/#resources). The response contains the diff of changes and the stack ID. Use this endpoint to install an InfluxDB template to an organization. @@ -17228,18 +17228,18 @@ paths: #### Custom values for templates - - Some templates may contain [environment references](/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. + - Some templates may contain [environment references](/influxdb/v2.4/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. To provide custom values for environment references, pass the _`envRefs`_ property in the request body. For more information and examples, see how to - [define environment references](/influxdb/latest/influxdb-templates/use/#define-environment-references). + [define environment references](/influxdb/v2.4/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use - [secrets](/influxdb/latest/security/secrets/). + [secrets](/influxdb/v2.4/security/secrets/). To provide custom secret values, pass the _`secrets`_ property in the request body. Don't expose secret values in templates. - For more information, see [how to pass secrets when installing a template](/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). + For more information, see [how to pass secrets when installing a template](/influxdb/v2.4/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions @@ -17252,8 +17252,8 @@ paths: #### Related guides - - [Use templates](/influxdb/latest/influxdb-templates/use/) - - [Stacks](/influxdb/latest/influxdb-templates/stacks/) + - [Use templates](/influxdb/v2.4/influxdb-templates/use/) + - [Stacks](/influxdb/v2.4/influxdb-templates/stacks/) operationId: ApplyTemplate requestBody: content: @@ -17539,7 +17539,7 @@ paths: /api/v2/users: get: description: | - Retrieves a list of [users](/influxdb/latest/reference/glossary/#user). + Retrieves a list of [users](/influxdb/v2.4/reference/glossary/#user). Default limit is `20`. To limit which users are returned, pass query parameters in your request. @@ -17548,7 +17548,7 @@ paths: | Action | Permission required | Restriction | |:-------|:--------------------|:------------| - | List all users | _[Operator token](/influxdb/latest/security/tokens/#operator-token)_ | | + | List all users | _[Operator token](/influxdb/v2.4/security/tokens/#operator-token)_ | | | List a specific user | `read-users` or `read-user USER_ID` | | Replace the following: @@ -17562,14 +17562,14 @@ paths: - $ref: '#/components/parameters/After' - description: | A user name. - Only lists the specified [user](/influxdb/latest/reference/glossary/#user). + Only lists the specified [user](/influxdb/v2.4/reference/glossary/#user). in: query name: name schema: type: string - description: | A user ID. - Only lists the specified [user](/influxdb/latest/reference/glossary/#user). + Only lists the specified [user](/influxdb/v2.4/reference/glossary/#user). in: query name: id schema: @@ -17618,7 +17618,7 @@ paths: - Users post: description: | - Creates a [user](/influxdb/latest/reference/glossary/#user) that can access InfluxDB. + Creates a [user](/influxdb/v2.4/reference/glossary/#user) that can access InfluxDB. Returns the user. Use this endpoint to create a user that can sign in to start a user session @@ -17640,12 +17640,12 @@ paths: | Action | Permission required | Restriction | |:-------|:--------------------|:------------| - | Create a user | _[Operator token](/influxdb/latest/security/tokens/#operator-token)_ | | + | Create a user | _[Operator token](/influxdb/v2.4/security/tokens/#operator-token)_ | | #### Related guides - - [Create a user](/influxdb/latest/users/create-user/) - - [Create an API token scoped to a user](/influxdb/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) + - [Create a user](/influxdb/v2.4/users/create-user/) + - [Create an API token scoped to a user](/influxdb/v2.4/security/tokens/create-token/#create-a-token-scoped-to-a-user) operationId: PostUsers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17742,17 +17742,17 @@ paths: - Users get: description: | - Retrieves a [user](/influxdb/latest/reference/glossary/#user). + Retrieves a [user](/influxdb/v2.4/reference/glossary/#user). #### Related guides - - [Manage users](/influxdb/latest/organizations/users/) + - [Manage users](/influxdb/v2.4/organizations/users/) operationId: GetUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Retrieves the specified [user](/influxdb/latest/reference/glossary/#user). + Retrieves the specified [user](/influxdb/v2.4/reference/glossary/#user). in: path name: userID required: true @@ -17815,7 +17815,7 @@ paths: #### Related guides - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) - - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) + - [InfluxDB OSS - Change your password](/influxdb/v2.4/users/change-password/) operationId: PostUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17890,7 +17890,7 @@ paths: #### Related guides - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) - - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) + - [InfluxDB OSS - Change your password](/influxdb/v2.4/users/change-password/) operationId: PutUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' @@ -18215,7 +18215,7 @@ paths: description: | Writes data to a bucket. - Use this endpoint to send data in [line protocol](/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](/influxdb/v2.4/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud @@ -18252,9 +18252,9 @@ paths: #### Related guides - - [Write data with the InfluxDB API](/influxdb/latest/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](/influxdb/latest/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](/influxdb/latest/write-data/troubleshoot/) + - [Write data with the InfluxDB API](/influxdb/v2.4/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](/influxdb/v2.4/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](/influxdb/v2.4/write-data/troubleshoot/) operationId: PostWrite parameters: - $ref: '#/components/parameters/TraceSpan' @@ -18310,7 +18310,7 @@ paths: #### Related guides - - [Troubleshoot issues writing data](/influxdb/latest/write-data/troubleshoot/) + - [Troubleshoot issues writing data](/influxdb/v2.4/write-data/troubleshoot/) in: header name: Accept schema: @@ -18393,7 +18393,7 @@ paths: #### Related guides - - [Best practices for optimizing writes](/influxdb/latest/write-data/best-practices/optimize-writes/) + - [Best practices for optimizing writes](/influxdb/v2.4/write-data/best-practices/optimize-writes/) required: true responses: '204': @@ -18411,7 +18411,7 @@ paths: #### Related guides - - [How to check for write errors](/influxdb/latest/write-data/troubleshoot/) + - [How to check for write errors](/influxdb/v2.4/write-data/troubleshoot/) '400': content: application/json: @@ -19040,7 +19040,7 @@ tags: #### Limitations API tokens are visible to the user who created the authorization and to any - user with an _[operator token](/influxdb/latest/security/tokens/#operator-token)_. + user with an _[operator token](/influxdb/v2.4/security/tokens/#operator-token)_. In InfluxDB OSS, even if an API token has `read-authorizations` permission, the token can't be used to view its authorization details. Tokens stop working when the user who created the token is deleted. @@ -19060,22 +19060,22 @@ tags: ### Related guides - - [Authorize API requests](/influxdb/latest/api-guide/api_intro/#authentication) - - [Manage API tokens](/influxdb/latest/security/tokens/) - - [Assign a token to a specific user](/influxdb/latest/security/tokens/create-token/) + - [Authorize API requests](/influxdb/v2.4/api-guide/api_intro/#authentication) + - [Manage API tokens](/influxdb/v2.4/security/tokens/) + - [Assign a token to a specific user](/influxdb/v2.4/security/tokens/create-token/) name: Authorizations - name: Backup - description: | - Store your data in InfluxDB [buckets](/influxdb/latest/reference/glossary/#bucket). + Store your data in InfluxDB [buckets](/influxdb/v2.4/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets - have a [retention period](/influxdb/latest/reference/glossary/#retention-period), + have a [retention period](/influxdb/v2.4/reference/glossary/#retention-period), a duration of time that each data point persists. InfluxDB drops all points with timestamps older than the bucket’s retention period. A bucket belongs to an organization. ### Related guides - - [Manage buckets](/influxdb/latest/organizations/buckets/) + - [Manage buckets](/influxdb/v2.4/organizations/buckets/) name: Buckets - name: Cells - name: Checks @@ -19088,10 +19088,10 @@ tags: | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| - | `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/latest/organizations/buckets/view-buckets/). | - | `bucketID` | string | The bucket ID ([find your bucket](/influxdb/latest/organizations/buckets/view-buckets/). | - | `org` | string | The organization name or ID ([find your organization](/influxdb/latest/organizations/view-orgs/). | - | `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/latest/organizations/view-orgs/). | + | `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/v2.4/organizations/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](/influxdb/v2.4/organizations/buckets/view-buckets/). | + | `org` | string | The organization name or ID ([find your organization](/influxdb/v2.4/organizations/view-orgs/). | + | `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/v2.4/organizations/view-orgs/). | name: Common parameters x-traitTag: true - name: Config @@ -19139,7 +19139,7 @@ tags: - name: NotificationEndpoints - name: NotificationRules - description: | - Create and manage your [organizations](/influxdb/latest/reference/glossary/#organization). + Create and manage your [organizations](/influxdb/v2.4/reference/glossary/#organization). An organization is a workspace for a group of users. Organizations can be used to separate different environments, projects, teams or users within InfluxDB. @@ -19188,10 +19188,10 @@ tags: Retrieve data, analyze queries, and get query suggestions. name: Query - description: | - See the [**API Quick Start**](/influxdb/latest/api-guide/api_intro/) + See the [**API Quick Start**](/influxdb/v2.4/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. - [**InfluxDB API client libraries**](/influxdb/latest/api-guide/client-libraries/) + [**InfluxDB API client libraries**](/influxdb/v2.4/api-guide/client-libraries/) are available for popular languages and ready to import into your application. name: Quick start x-traitTag: true @@ -19212,7 +19212,7 @@ tags: | `200` | Success | | | `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. | | `400` | Bad request | May indicate one of the following:
  • Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your `_monitoring` bucket.
  • `Authorization` header is missing or malformed or the API token doesn't have permission for the operation.
| - | `401` | Unauthorized | May indicate one of the following:
  • `Authorization: Token` header is missing or malformed
  • API token value is missing from the header
  • API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/latest/security/tokens/)
| + | `401` | Unauthorized | May indicate one of the following:
  • `Authorization: Token` header is missing or malformed
  • API token value is missing from the header
  • API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/v2.4/security/tokens/)
| | `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. | | `413` | Request entity too large | Request payload exceeds the size limit. | | `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. | @@ -19243,8 +19243,8 @@ tags: #### Related guides - - [Get started with tasks](/influxdb/latest/process-data/get-started/) - - [Common data processing tasks](/influxdb/latest/process-data/common-tasks/) + - [Get started with tasks](/influxdb/v2.4/process-data/get-started/) + - [Common data processing tasks](/influxdb/v2.4/process-data/common-tasks/) name: Tasks - name: Telegraf Plugins - name: Telegrafs @@ -19269,8 +19269,8 @@ tags: #### Related guides - - [InfluxDB stacks](/influxdb/latest/influxdb-templates/stacks/) - - [InfluxDB templates](/influxdb/latest/influxdb-templates/) + - [InfluxDB stacks](/influxdb/v2.4/influxdb-templates/stacks/) + - [InfluxDB templates](/influxdb/v2.4/influxdb-templates/) name: Templates - description: | Manage users for your organization. @@ -19287,13 +19287,13 @@ tags: #### Related guides - - [Manage users](/influxdb/latest/influxdb/latest/users/) - - [Create a token scoped to a user](/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) + - [Manage users](/influxdb/v2.4/influxdb/latest/users/) + - [Create a token scoped to a user](/influxdb/v2.4/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) name: Users - name: Variables - name: Views - description: | - Write time series data to [buckets](/influxdb/latest/reference/glossary/#bucket). + Write time series data to [buckets](/influxdb/v2.4/reference/glossary/#bucket). name: Write x-tagGroups: - name: Overview diff --git a/api-docs/v2.5/ref.yml b/api-docs/v2.5/ref.yml index 96ca5d346..6c9934d3c 100644 --- a/api-docs/v2.5/ref.yml +++ b/api-docs/v2.5/ref.yml @@ -363,7 +363,7 @@ components: type: string status: default: active - description: Status of the token. If `inactive`, requests using the token will be rejected. + description: Status of the token. If `inactive`, InfluxDB rejects requests that use the token. enum: - active - inactive @@ -2365,21 +2365,21 @@ components: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - properties: orgID: - description: The ID of the organization that the authorization is scoped to. + description: The organization ID. Identifies the organization that the authorization is scoped to. type: string permissions: description: | - A list of permissions that provide `read` and `write` access to organization resources. + The list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: '#/components/schemas/Permission' minItems: 1 type: array token: - description: A name that you provide for the authorization. + description: The name that you provide for the authorization. type: string userID: - description: The ID of the user that the authorization is scoped to. + description: The user ID. Identifies the user that the authorization is scoped to. type: string type: object required: @@ -3939,7 +3939,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](/influxdb/latest/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -6697,7 +6697,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides @@ -6754,16 +6754,19 @@ paths: To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations. - #### InfluxDB OSS + #### InfluxDB Cloud - - InfluxDB OSS returns - [API token](/influxdb/latest/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. + - InfluxDB Cloud doesn't expose [API token](/influxdb/latest/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. #### Required permissions - - An _[operator token](/influxdb/latest/security/tokens/#operator-token)_. + To retrieve an authorization, the request must use an API token that has the + following permissions: + + - `read-authorizations` + - `read-user` for the user that the authorization is scoped to #### Related guides @@ -6797,13 +6800,44 @@ paths: name: org schema: type: string + - description: | + An API [token](/influxdb/latest/reference/glossary/#token) value. + Specifies an authorization by its `token` property value + and returns the authorization. + + #### InfluxDB OSS + + - Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, + applies other parameters, and then returns the result. + + #### Limitations + + - The parameter is non-repeatable. If you specify more than one, + only the first one is used. If a resource with the specified + property value doesn't exist, then the response body contains an empty list. + in: query + name: token + schema: + type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Authorizations' - description: Success. The response body contains a list of authorizations. + description: | + Success. The response body contains a list of authorizations. + + If the response body is missing authorizations that you expect, check that the API + token used in the request has `read-user` permission for the users (`userID` property value) + in those authorizations. + + #### InfluxDB OSS + + - **Warning**: The response body contains authorizations with their + [API token](/influxdb/latest/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. '400': $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6816,7 +6850,7 @@ paths: description: Unexpected error summary: List authorizations tags: - - Authorizations + - Authorizations (API tokens) - Security and access endpoints post: description: | @@ -6825,21 +6859,24 @@ paths: Use this endpoint to create an authorization, which generates an API token with permissions to `read` or `write` to a specific resource or `type` of resource. - The response contains the new authorization with the generated API token. - - #### Limitations + The API token is the authorization's `token` property value. To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens. - - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any - user with an _[operator token](/influxdb/latest/security/tokens/#operator-token)_. - - You can't update an authorization's permissions. - - Even if an API token has `read-authorizations` permission, the - token can't be used to view its authorization details. - - A token stops working when the user who created the authorization is deleted. + - InfluxDB allows access to the API token value immediately after the authorization is created. + - You can’t change access (read/write) permissions for an API token after it’s created. + - Tokens stop working when the user who created the token is deleted. - We recommend creating a generic user to create and manage tokens for writing data. + We recommend the following for managing your tokens: + + - Create a generic user to create and manage tokens for writing data. + - Store your tokens in a secure password vault for future access. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to #### Related guides @@ -6868,7 +6905,8 @@ paths: schema: $ref: '#/components/schemas/Authorization' description: | - Success. The authorization is created. The response body contains the authorization. + Success. The authorization is created. The response body contains the + authorization. '400': $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6881,13 +6919,21 @@ paths: description: Unexpected error summary: Create an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/authorizations/{authID}: delete: + description: | + Deletes an authorization. + + Use the endpoint to delete an API token. + + If you want to disable an API token instead of delete it, + [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to delete. + - description: An authorization ID. Specifies the authorization to delete. in: path name: authID required: true @@ -6895,18 +6941,70 @@ paths: type: string responses: '204': - description: Authorization deleted + description: Success. The authorization is deleted. + '400': + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints get: + description: | + Retrieves an authorization. + + Use this endpoint to retrieve information about an API token, including + the token's permissions and the user that the token is scoped to. + + #### InfluxDB OSS + + - InfluxDB OSS returns + [API token](/influxdb/latest/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](/influxdb/latest/security/tokens/view-tokens/) + externalDocs: + description: View tokens + url: https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/ operationId: GetAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to get. + - description: An authorization ID. Specifies the authorization to retrieve. in: path name: authID required: true @@ -6918,19 +7016,56 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Authorization details + description: Success. The response body contains the authorization. + '400': + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: - - Authorizations + - Authorizations (API tokens) - Security and access endpoints patch: + description: | + Updates an authorization. + + Use this endpoint to set an API token's status to be _active_ or _inactive_. + InfluxDB rejects requests that use inactive API tokens. operationId: PatchAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to update. + - description: An authorization ID. Specifies the authorization to update. in: path name: authID required: true @@ -6941,7 +7076,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: Authorization to update + description: In the request body, provide the authorization properties to update. required: true responses: '200': @@ -6949,13 +7084,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: The active or inactive authorization + description: Success. The response body contains the updated authorization. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: Update an authorization to be active or inactive + summary: Update an API token to be active or inactive tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/backup/kv: get: deprecated: true @@ -8084,7 +8220,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8100,7 +8236,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8165,7 +8301,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8180,7 +8316,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8266,7 +8402,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8282,7 +8418,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -10571,7 +10707,7 @@ paths: 1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve feature flags and their values. - 2. Follow the instructions to [enable, disable, or override values for feature flags](/influxdb/latest/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](/influxdb/latest/reference/config-options/#feature-flags). 3. **Optional**: To confirm that your change is applied, do one of the following: - Send a request to this endpoint to retrieve the current feature flag values. @@ -10580,7 +10716,7 @@ paths: #### Related guides - - [InfluxDB configuration options](/influxdb/latest/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](/influxdb/latest/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11930,7 +12066,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12028,7 +12164,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12127,7 +12263,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12188,7 +12324,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -12250,7 +12386,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -12260,7 +12396,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: PostOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12334,7 +12470,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12349,7 +12485,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15782,7 +15918,6 @@ paths: Only returns [tasks](/influxdb/latest/reference/glossary/#task) owned by the specified [organization](/influxdb/latest/reference/glossary/#organization). in: query name: orgID - required: true schema: type: string - description: | @@ -16313,7 +16448,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](/influxdb/latest/reference/glossary/#task). operationId: GetTasksIDMembers @@ -16351,7 +16486,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task](/influxdb/latest/reference/glossary/#task) and then returns the member. @@ -16398,7 +16533,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDMembersID @@ -16433,7 +16568,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. operationId: GetTasksIDOwners @@ -16485,7 +16620,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. @@ -16562,7 +16697,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task](/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDOwnersID @@ -19361,23 +19496,9 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. - #### Limitations - - To follow best practices for secure API token generation and retrieval, - InfluxDB enforces access restrictions on API tokens. - - - InfluxDB allows access to the API token value immediately after the authorization is created. - - You can’t change access (read/write) permissions for an API token after it’s created. - - Tokens stop working when the user who created the token is deleted. - - API tokens are visible to the user who created the authorization and to any - user with an _[operator token](/influxdb/latest/security/tokens/#operator-token)_. - In InfluxDB OSS, even if an API token has `read-authorizations` permission, the - token can't be used to view its authorization details. - We recommend creating a generic user to create and manage tokens for writing data. - #### User sessions with authorizations + ### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If a user signs in with username and password, creating a _user session_, @@ -19395,7 +19516,7 @@ tags: - [Authorize API requests](/influxdb/latest/api-guide/api_intro/#authentication) - [Manage API tokens](/influxdb/latest/security/tokens/) - [Assign a token to a specific user](/influxdb/latest/security/tokens/create-token/) - name: Authorizations + name: Authorizations (API tokens) - name: Backup - description: | Store your data in InfluxDB [buckets](/influxdb/latest/reference/glossary/#bucket). @@ -19487,7 +19608,7 @@ tags: | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). | | `after` | string (resource ID) | Only returns resources created after the specified resource. | - #### Limitations + ### Limitations - For specific endpoint parameters and examples, see the endpoint definition. - If you specify an `offset` parameter value greater than the total number of records, @@ -19577,7 +19698,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -19585,7 +19706,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks](/influxdb/latest/process-data/get-started/) - [Common data processing tasks](/influxdb/latest/process-data/common-tasks/) @@ -19611,7 +19732,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](/influxdb/latest/influxdb-templates/stacks/) - [InfluxDB templates](/influxdb/latest/influxdb-templates/) @@ -19622,14 +19743,14 @@ tags: To grant a user permission to access data, add them as a member of an organization and provide them with an API token. - #### User sessions with authorizations + ### User sessions with authorizations Optionally, you can scope an authorization (and its API token) to a user. If a user signs in with username and password, creating a _user session_, the session carries the permissions granted by all the user's authorizations. To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). - #### Related guides + ### Related guides - [Manage users](/influxdb/latest/influxdb/latest/users/) - [Create a token scoped to a user](/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) @@ -19656,7 +19777,7 @@ x-tagGroups: - System information endpoints - name: All endpoints tags: - - Authorizations + - Authorizations (API tokens) - Backup - Buckets - Cells diff --git a/content/influxdb/v2.5/security/tokens/view-tokens.md b/content/influxdb/v2.5/security/tokens/view-tokens.md index 0c2a36b8c..778ca9000 100644 --- a/content/influxdb/v2.5/security/tokens/view-tokens.md +++ b/content/influxdb/v2.5/security/tokens/view-tokens.md @@ -107,4 +107,4 @@ To filter authorizations by organization when using an operator token, include a {{% /oss-only %}} -See the [`/authorizations` endpoint documentation](/influxdb/v2.5/api/#tag/Authorizations) for more information about available parameters. +See the [`/authorizations` endpoint documentation](/influxdb/v2.5/api/#tag/Authorizations-(API-tokens)) for more information about available parameters.