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: | - | `401` | Unauthorized | May indicate one of the following: | + | `401` | Unauthorized | May indicate one of the following: | | `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.