From e7476730ae438b7875f6522184fe80d14a8a77b6 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 4 Nov 2022 13:23:07 -0500 Subject: [PATCH 1/2] docs: complete merge of authorizations paths, describe auths: - Closes #524 - Closes #525 - Merge Cloud /authorizations into common - the only difference is support for ?token= in Cloud. - Describe the difference. - Describe required permissions. - Replace platform-specific /authorizations and /authorizations/ with common. - Describe patch and delete. - Cleanup. --- contracts/cloud-diff.yml | 415 ++----- contracts/cloud.json | 638 +++++----- contracts/cloud.yml | 601 ++++++---- contracts/common.yml | 674 ++++++++--- contracts/legacy.yml | 10 +- contracts/oss-diff.yml | 405 ++----- contracts/oss.json | 629 ++++++---- contracts/oss.yml | 1045 +++++++++-------- contracts/priv/cloud-priv.yml | 2 +- contracts/ref/cloud.yml | 238 +++- contracts/ref/oss.yml | 695 ++++++----- scripts/generate.sh | 5 +- src/cloud.yml | 4 - src/cloud/paths/authorizations.yml | 145 --- src/cloud/paths/authorizations_authID.yml | 73 -- src/cloud/tags.yml | 28 +- src/common/_paths.yml | 4 + src/common/paths/authorizations.yml | 77 +- src/common/paths/authorizations_authID.yml | 120 +- .../schemas/AuthorizationUpdateRequest.yml | 2 +- .../LegacyAuthorizationPostRequest.yml | 8 +- src/oss.yml | 4 - src/oss/tags.yml | 28 +- 23 files changed, 3162 insertions(+), 2688 deletions(-) delete mode 100644 src/cloud/paths/authorizations.yml delete mode 100644 src/cloud/paths/authorizations_authID.yml diff --git a/contracts/cloud-diff.yml b/contracts/cloud-diff.yml index f19781072..1f86f43bb 100644 --- a/contracts/cloud-diff.yml +++ b/contracts/cloud-diff.yml @@ -426,342 +426,6 @@ paths: default: description: Unexpected error $ref: '#/paths/~1tasks/get/responses/default' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - summary: List authorizations - description: | - 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. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - - `read-authorizations` - - #### Related guides - - - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: | - An organization ID. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value. - Returns the authorization for the specified token. - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - type: object - properties: - links: - readOnly: true - $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' - authorizations: - type: array - items: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1tasks/get/responses/default' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token). - - 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 - - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud 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. - - 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. - - #### Related guides - - - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - required: - - orgID - - permissions - allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' - - type: object - properties: - orgID: - type: string - description: | - An organization ID. - Specifies the organization that owns the authorization. - userID: - type: string - description: | - A user ID. - Specifies the user that the authorization is scoped to. - - When a user authenticates with username and password, - InfluxDB generates a _user session_ with all the permissions - specified by all the user's authorizations. - permissions: - type: array - minItems: 1 - description: | - A list of permissions for an authorization. - In the list, provide at least one `permission` object. - - In a `permission`, the `resource.type` property grants access to all - resources of the specified type. - To grant access to only a specific resource, specify the - `resource.id` property. - items: - required: - - action - - resource - properties: - action: - type: string - enum: - - read - - write - resource: - type: object - required: - - type - properties: - type: - type: string - enum: - - authorizations - - buckets - - dashboards - - orgs - - tasks - - telegrafs - - users - - variables - - secrets - - labels - - views - - documents - - notificationRules - - notificationEndpoints - - checks - - dbrp - - annotations - - sources - - scrapers - - notebooks - - remotes - - replications - - instance - - flows - - functions - - subscriptions - description: | - A resource type. - Identifies the API resource's type (or _kind_). - id: - type: string - description: | - A resource ID. - Identifies a specific resource. - name: - type: string - description: | - The name of the resource. - _Note: not all resource types have a `name` property_. - orgID: - type: string - description: | - An organization ID. - Identifies the organization that owns the resource. - org: - type: string - description: | - An organization name. - The organization that owns the resource. - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1tasks/get/responses/default' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - summary: Retrieve an authorization - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update authorization status - description: Update an authorization's status to `active` or `inactive`. - requestBody: - description: The updated Authorization object. - required: true - content: - application/json: - schema: - properties: - status: - description: 'Status of the token. If `inactive`, requests using the token will be rejected.' - default: active - type: string - enum: - - active - - inactive - description: - type: string - description: A description of the token. - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to update. - responses: - '200': - description: The updated authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' /variables: get: operationId: GetVariables @@ -4039,7 +3703,17 @@ components: - orgID - permissions allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' + - properties: + status: + description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + default: active + type: string + enum: + - active + - inactive + description: + type: string + description: A description of the token. - type: object properties: createdAt: @@ -4062,7 +3736,72 @@ components: The list of permissions. An authorization must have at least one permission. items: - $ref: '#/paths/~1authorizations/post/requestBody/content/application~1json/schema/allOf/1/properties/permissions/items' + required: + - action + - resource + properties: + action: + type: string + enum: + - read + - write + resource: + type: object + required: + - type + properties: + type: + type: string + enum: + - authorizations + - buckets + - dashboards + - orgs + - tasks + - telegrafs + - users + - variables + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + - annotations + - sources + - scrapers + - notebooks + - remotes + - replications + - instance + - flows + - functions + - subscriptions + description: | + A resource type. + Identifies the API resource's type (or _kind_). + id: + type: string + description: | + A resource ID. + Identifies a specific resource. + name: + type: string + description: | + The name of the resource. + _Note: not all resource types have a `name` property_. + orgID: + type: string + description: | + An organization ID. + Identifies the organization that owns the resource. + org: + type: string + description: | + An organization name. + The organization that owns the resource. id: readOnly: true type: string diff --git a/contracts/cloud.json b/contracts/cloud.json index 9640cc831..efa67d9c1 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -17,7 +17,7 @@ "tags": [ { "name": "Authorizations", - "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nIn InfluxDB Cloud, an authorization with `read-authorizations` permission\ncan be used to view other authorizations.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- InfluxDB allows access to the API token value immediately after the authorization is created.\n- You can’t change access (read/write) permissions for an API token after it’s created.\n- Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n#### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf the user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" + "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf the user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" }, { "name": "Buckets", @@ -25,7 +25,7 @@ }, { "name": "Invokable Scripts", - "description": "Store, manage, and execute scripts in InfluxDB.\nA script stores your custom Flux script and provides an invokable\nendpoint that accepts runtime parameters.\nIn a script, you can specify custom runtime parameters\n(`params`)--for example, `params.myparameter`.\nOnce you create a script, InfluxDB generates an\n[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)\nfor your organization.\nYou can run the script from API requests and tasks, defining parameter\nvalues for each run.\nWhen the script runs, InfluxDB replaces `params` references in the\nscript with the runtime parameter values you define.\n\nUse the `/api/v2/scripts` endpoints to create and manage scripts.\nSee related guides to learn how to define parameters and execute scripts.\n\n#### Related guides\n\n- [Invoke custom scripts]({{% INFLUXDB_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests.\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n" + "description": "Store, manage, and execute scripts in InfluxDB.\nA script stores your custom Flux script and provides an invokable\nendpoint that accepts runtime parameters.\nIn a script, you can specify custom runtime parameters\n(`params`)--for example, `params.myparameter`.\nOnce you create a script, InfluxDB generates an\n[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)\nfor your organization.\nYou can run the script from API requests and tasks, defining parameter\nvalues for each run.\nWhen the script runs, InfluxDB replaces `params` references in the\nscript with the runtime parameter values you define.\n\nUse the `/api/v2/scripts` endpoints to create and manage scripts.\nSee related guides to learn how to define parameters and execute scripts.\n\n### Related guides\n\n- [Invoke custom scripts]({{% INFLUXDB_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests.\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n" }, { "name": "Delete", @@ -41,15 +41,15 @@ }, { "name": "Tasks", - "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n#### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in this object:\n\n\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Create a script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script)\n" + "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in this object:\n\n\n\n### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Create a script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script)\n" }, { "name": "Templates", - "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for resources.\nUse InfluxDB templates to configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n#### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" + "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for resources.\nUse InfluxDB templates to configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" }, { "name": "Users", - "description": "Retrieve specific users.\n\nInfluxDB Cloud lets you invite and collaborate with multiple users in your organization.\nTo invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);\nyou can't use the InfluxDB API to manage users in InfluxDB Cloud.\nOnce a user is added to your organization, you can use the\n`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to\nview specific members.\n\n#### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n" + "description": "Retrieve specific users.\n\nInfluxDB Cloud lets you invite and collaborate with multiple users in your organization.\nTo invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);\nyou can't use the InfluxDB API to manage users in InfluxDB Cloud.\nOnce a user is added to your organization, you can use the\n`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to\nview specific members.\n\n### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n" }, { "name": "Write", @@ -83,7 +83,7 @@ { "name": "Pagination", "x-traitTag": true, - "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n | Query parameter | Value type | Description |\n |:------------------------ |:--------------------- |:-------------------------------------------|\n | `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n | `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n #### Limitations\n\n - For specific endpoint parameters and examples, see the endpoint definition.\n - If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" + "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n | Query parameter | Value type | Description |\n |:------------------------ |:--------------------- |:-------------------------------------------|\n | `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n | `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n ### Limitations\n\n - For specific endpoint parameters and examples, see the endpoint definition.\n - If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" }, { "name": "Response codes", @@ -11207,6 +11207,370 @@ } } }, + "/authorizations": { + "get": { + "operationId": "GetAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "List authorizations", + "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\nTo retrieve an authorization, the request must use an API token that has the\nfollowing permissions:\n\n- `read-authorizations`\n- `read-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "query", + "name": "userID", + "schema": { + "type": "string" + }, + "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "user", + "schema": { + "type": "string" + }, + "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "orgID", + "schema": { + "type": "string" + }, + "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." + }, + { + "in": "query", + "name": "org", + "schema": { + "type": "string" + }, + "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + }, + { + "in": "query", + "name": "token", + "schema": { + "type": "string" + }, + "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nSpecifies an authorization by its `token` property value\nand returns the authorization.\n\n#### InfluxDB OSS\n\n- Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,\n applies other parameters, and then returns the result.\n\n#### Limitations\n\n- The parameter is non-repeatable. If you specify more than one,\n only the first one is used. If a resource with the specified\n property value doesn't exist, then the response body contains an empty list.\n" + } + ], + "responses": { + "200": { + "description": "Success. The response body contains a list of authorizations.\n\nIf the response body is missing authorizations that you expect, check that the API\ntoken used in the request has `read-user` permission for the users (`userID` property value)\nin those authorizations.\n\n#### InfluxDB OSS\n\n- **Warning**: The response body contains authorizations with their\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in clear text.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorizations" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "post": { + "operationId": "PostAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Create an authorization", + "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe API token is the authorization's `token` property value.\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n - InfluxDB allows access to the API token value immediately after the authorization is created.\n - You can’t change access (read/write) permissions for an API token after it’s created.\n - Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n - Create a generic user to create and manage tokens for writing data.\n - Store your tokens in a secure password vault for future access.\n\n#### Required permissions\n\n- `write-authorizations`\n- `write-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + } + ], + "requestBody": { + "description": "The authorization to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationPostRequest" + }, + "examples": { + "AuthorizationPostRequest": { + "$ref": "#/components/examples/AuthorizationPostRequest" + }, + "AuthorizationWithResourcePostRequest": { + "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" + }, + "AuthorizationWithUserPostRequest": { + "$ref": "#/components/examples/AuthorizationWithUserPostRequest" + } + } + } + } + }, + "responses": { + "201": { + "description": "Success. The authorization is created. The response body contains the\nauthorization.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, + "/authorizations/{authID}": { + "get": { + "operationId": "GetAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Retrieve an authorization", + "description": "Retrieves an authorization.\n\nUse this endpoint to retrieve information about an API token, including\nthe token's permissions and the user that the token is scoped to.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "externalDocs": { + "url": "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/", + "description": "View tokens" + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to retrieve." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "patch": { + "operationId": "PatchAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Update an API token to be active or inactive", + "description": "Updates an authorization.\n\nUse this endpoint to set an API token's status to be _active_ or _inactive_.\nInfluxDB rejects requests that use inactive API tokens.\n", + "requestBody": { + "description": "In the request body, provide the authorization properties to update.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationUpdateRequest" + } + } + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to update." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the updated authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "delete": { + "operationId": "DeleteAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Delete an authorization", + "description": "Deletes an authorization.\n\nUse the endpoint to delete an API token.\n\nIf you want to disable an API token instead of delete it,\n[update the authorization's status to `inactive`](#operation/PatchAuthorizationsID).\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to delete." + } + ], + "responses": { + "204": { + "description": "Success. The authorization is deleted." + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, "/users": { "get": { "operationId": "GetUsers", @@ -11587,266 +11951,6 @@ } } }, - "/authorizations": { - "get": { - "operationId": "GetAuthorizations", - "tags": [ - "Authorizations" - ], - "summary": "List authorizations", - "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations for the organization.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\n- `read-authorizations`\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "query", - "name": "userID", - "schema": { - "type": "string" - }, - "description": "A user ID.\nOnly returns authorizations scoped to the specified\n[user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "user", - "schema": { - "type": "string" - }, - "description": "A user name.\nOnly returns authorizations scoped to the specified\n[user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "orgID", - "schema": { - "type": "string" - }, - "description": "An organization ID.\nOnly returns authorizations that belong to the specified\n[organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" - }, - { - "in": "query", - "name": "org", - "schema": { - "type": "string" - }, - "description": "An organization name.\nOnly returns authorizations that belong to the specified\n[organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" - }, - { - "in": "query", - "name": "token", - "schema": { - "type": "string" - }, - "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nReturns the authorization for the specified token.\n" - } - ], - "responses": { - "200": { - "description": "Success. The response body contains a list of authorizations.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorizations" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "post": { - "operationId": "PostAuthorizations", - "tags": [ - "Authorizations" - ], - "summary": "Create an authorization", - "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB Cloud enforces access restrictions on API tokens.\n\n- InfluxDB only allows access to the API token value immediately after the authorization is created.\n- You can't update an authorization's permissions.\n- A token stops working when the user who created the authorization is deleted.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - } - ], - "requestBody": { - "description": "The authorization to create.", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationPostRequest" - }, - "examples": { - "AuthorizationPostRequest": { - "$ref": "#/components/examples/AuthorizationPostRequest" - }, - "AuthorizationWithResourcePostRequest": { - "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" - }, - "AuthorizationWithUserPostRequest": { - "$ref": "#/components/examples/AuthorizationWithUserPostRequest" - } - } - } - } - }, - "responses": { - "201": { - "description": "Success. The authorization is created. The response body contains the authorization.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/authorizations/{authID}": { - "get": { - "operationId": "GetAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Retrieve an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The identifier of the authorization to get." - } - ], - "responses": { - "200": { - "description": "Authorization details", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "patch": { - "operationId": "PatchAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Update authorization status", - "description": "Update an authorization's status to `active` or `inactive`.", - "requestBody": { - "description": "The updated Authorization object.", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationUpdateRequest" - } - } - } - }, - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The identifier of the authorization to update." - } - ], - "responses": { - "200": { - "description": "The updated authorization.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "delete": { - "operationId": "DeleteAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Delete an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The identifier of the authorization to delete." - } - ], - "responses": { - "204": { - "description": "Authorization deleted" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, "/variables": { "get": { "operationId": "GetVariables", @@ -14300,7 +14404,7 @@ "AuthorizationUpdateRequest": { "properties": { "status": { - "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.", "default": "active", "type": "string", "enum": [ diff --git a/contracts/cloud.yml b/contracts/cloud.yml index ea80266e5..cd0d75901 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -18,24 +18,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_, @@ -83,7 +71,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](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -112,7 +100,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -120,7 +108,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/cloud/process-data/get-started/) - [Common data processing tasks](https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/) @@ -143,7 +131,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/) @@ -158,14 +146,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](https://docs.influxdata.com/influxdb/cloud/organizations/users/) - name: Write @@ -231,7 +219,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, @@ -9054,6 +9042,357 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: List authorizations + description: | + Lists authorizations. + + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### 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 + + - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization).' + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token](https://docs.influxdata.com/influxdb/cloud/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. + responses: + '200': + 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + post: + operationId: PostAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token). + + 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 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. + + - 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. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to + + #### Related guides + + - [Create a token](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + examples: + AuthorizationPostRequest: + $ref: '#/components/examples/AuthorizationPostRequest' + AuthorizationWithResourcePostRequest: + $ref: '#/components/examples/AuthorizationWithResourcePostRequest' + AuthorizationWithUserPostRequest: + $ref: '#/components/examples/AuthorizationWithUserPostRequest' + responses: + '201': + description: | + Success. The authorization is created. The response body contains the + authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Retrieve an authorization + 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) + externalDocs: + url: 'https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/' + description: View tokens + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to retrieve. + responses: + '200': + description: Success. The response body contains the authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. + requestBody: + description: 'In the request body, provide the authorization properties to update.' + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to update. + responses: + '200': + description: Success. The response body contains the updated authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Delete an authorization + 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). + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to delete. + responses: + '204': + description: Success. The authorization is deleted. + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' /users: get: operationId: GetUsers @@ -9416,226 +9755,6 @@ paths: default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - summary: List authorizations - description: | - 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. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - - `read-authorizations` - - #### Related guides - - - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: | - An organization ID. - Only returns authorizations that belong to the specified - [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified - [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) value. - Returns the authorization for the specified token. - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token). - - 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 - - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud 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. - - 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. - - #### Related guides - - - [Create a token](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPostRequest' - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - summary: Retrieve an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update authorization status - description: Update an authorization's status to `active` or `inactive`. - requestBody: - description: The updated Authorization object. - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to update. - responses: - '200': - description: The updated authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' /variables: get: operationId: GetVariables @@ -11615,7 +11734,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: diff --git a/contracts/common.yml b/contracts/common.yml index dcf366600..8f4ab8c9c 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -14,7 +14,7 @@ paths: summary: Create a user session. description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user), + for a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the @@ -120,7 +120,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -165,7 +165,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -1012,7 +1012,7 @@ paths: description: | Writes data to a bucket. - Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud @@ -1047,12 +1047,12 @@ paths: #### Related guides - - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) requestBody: description: | - In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/). + In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/). To send compressed data, do the following: @@ -1062,7 +1062,7 @@ paths: #### Related guides - - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) + - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) required: true content: text/plain: @@ -1130,7 +1130,7 @@ paths: #### Related guides - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) schema: type: string description: Error content type. @@ -1205,7 +1205,7 @@ paths: #### Related guides - - [How to check for write errors](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [How to check for write errors](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) '400': description: | Bad request. The response body contains detail about the error. @@ -1363,8 +1363,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/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/). x-codeSamples: @@ -1390,8 +1390,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). required: true content: application/json: @@ -2284,7 +2284,7 @@ paths: summary: Generate a query Abstract Syntax Tree (AST) description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#abstract-syntax-tree-ast) + Tree (AST)](https://docs.influxdata.com/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query @@ -3617,7 +3617,7 @@ paths: #### Related guides - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/query-data/execute-queries/influx-api/) + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3748,9 +3748,9 @@ paths: description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#adjustable-service-quotas) + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#global-limits) + [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: @@ -3772,19 +3772,19 @@ paths: - Buckets summary: List buckets description: | - Lists [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Lists [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) associated with the authorization - ([API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token)). + ([API token](https://docs.influxdata.com/influxdb/latest/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`. #### InfluxDB OSS - - If you use an _[operator token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/#operator-token)_ + - If you use an _[operator token](https://docs.influxdata.com/influxdb/latest/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 @@ -3795,11 +3795,11 @@ paths: | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/v2.3/reference/internals/system-buckets/) | `read-orgs` | + | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - - [Manage buckets](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -3908,10 +3908,10 @@ paths: - Buckets summary: Create a bucket description: | - Creates a [bucket](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket) + Creates a [bucket](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket) and returns the bucket resource. The default data - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period) + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS @@ -3930,8 +3930,8 @@ paths: #### Related Guides - - [Create a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/bucket/create) + - [Create a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/bucket/create) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -4137,7 +4137,7 @@ paths: #### Related Guides - - [Update a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/update-bucket/) + - [Update a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/update-bucket/) requestBody: description: The bucket update to apply. required: true @@ -4283,7 +4283,7 @@ paths: #### Related Guides - - [Delete a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4369,7 +4369,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4433,7 +4433,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4559,18 +4559,18 @@ paths: description: | Lists all users for a bucket. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4629,18 +4629,18 @@ paths: description: | Add a user to a bucket and return the new user information. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4720,8 +4720,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4762,7 +4762,7 @@ paths: - Buckets summary: List all owners of a bucket description: | - Lists all [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Lists all [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) of a bucket. Bucket owners have permission to delete buckets and remove user and member @@ -4791,7 +4791,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4842,7 +4842,7 @@ paths: - Buckets summary: Add an owner to a bucket description: | - Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. @@ -4871,7 +4871,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4973,7 +4973,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5015,7 +5015,7 @@ paths: - Security and access endpoints summary: List organizations description: | - Lists [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization/). + Lists [organizations](https://docs.influxdata.com/influxdb/latest/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`. @@ -5026,7 +5026,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -5097,7 +5097,7 @@ paths: - Organizations summary: Create an organization description: | - Creates an [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Creates an [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud @@ -5106,7 +5106,7 @@ paths: #### Related guides - - [Manage organizations](https://docs.influxdata.com/influxdb/v2.3/organizations) + - [Manage organizations](https://docs.influxdata.com/influxdb/latest/organizations) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -5187,7 +5187,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5256,7 +5256,7 @@ paths: #### Related Guides - - [Update an organization](https://docs.influxdata.com/influxdb/v2.3/organizations/update-org/) + - [Update an organization](https://docs.influxdata.com/influxdb/latest/organizations/update-org/) requestBody: description: The organization update to apply. required: true @@ -5324,7 +5324,7 @@ paths: #### Related guides - - [Delete organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/delete-orgs/) + - [Delete organizations](https://docs.influxdata.com/influxdb/latest/organizations/delete-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5438,10 +5438,10 @@ paths: description: | Lists all users that belong to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5463,8 +5463,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5536,10 +5536,10 @@ paths: description: | Add a user to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5559,8 +5559,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5660,7 +5660,7 @@ paths: #### Related guides - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5843,7 +5843,7 @@ paths: - Security and access endpoints summary: Remove an owner from an organization description: | - Removes an [owner](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) from + Removes an [owner](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member @@ -5997,7 +5997,7 @@ paths: #### Related guides - - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/). + - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/). parameters: - in: query name: orgID @@ -6006,7 +6006,7 @@ paths: type: string description: | An organization ID. - Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). #### InfluxDB Cloud @@ -6115,8 +6115,8 @@ paths: #### Related guides - - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). + - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/init/). + - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). requestBody: description: The stack to create. required: true @@ -6311,8 +6311,8 @@ paths: summary: Apply or dry-run a template description: | Applies a template to - create or update a [stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) of InfluxDB - [resources](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/export/all/#resources). + create or update a [stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) of InfluxDB + [resources](https://docs.influxdata.com/influxdb/latest/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. @@ -6328,18 +6328,18 @@ paths: #### Custom values for templates - - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. + - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use - [secrets](https://docs.influxdata.com/influxdb/v2.3/security/secrets/). + [secrets](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template). + For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions @@ -6352,8 +6352,8 @@ paths: #### Related guides - - [Use templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/) - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) + - [Use templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) requestBody: required: true description: | @@ -6639,7 +6639,7 @@ paths: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. If you don't pass query parameters, InfluxDB returns all runs for the task @@ -6653,7 +6653,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to list runs for. - in: query name: after @@ -6675,7 +6675,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after the specified time. - in: query name: beforeTime @@ -6683,7 +6683,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before the specified time. responses: '200': @@ -6726,7 +6726,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to run. requestBody: content: @@ -6765,7 +6765,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -6777,7 +6777,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID @@ -6831,7 +6831,7 @@ paths: - Tasks summary: Cancel a running task description: | - Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to cancel a running task. @@ -6847,7 +6847,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to cancel. - in: path name: runID @@ -6898,7 +6898,7 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to retry and then returns the scheduled run. To manually start a _new_ task run, use the @@ -6921,7 +6921,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: @@ -6988,7 +6988,7 @@ paths: - Tasks summary: List logs for a task description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). When a task runs, InfluxDB creates a `run` record in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. @@ -7002,7 +7002,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve logs for.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for.' responses: '200': description: | @@ -7058,7 +7058,7 @@ paths: Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7066,7 +7066,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the run belongs to.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to.' - in: path name: runID schema: @@ -7163,7 +7163,7 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to add a label to a task. Labels are a way to add metadata to InfluxDB resources. @@ -7178,7 +7178,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. requestBody: description: | In the request body, provide an object that specifies the label. @@ -7211,7 +7211,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7221,7 +7221,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: @@ -7260,7 +7260,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](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -7269,7 +7269,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7317,7 +7317,7 @@ paths: - Users summary: Update a password description: | - Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/latest/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: @@ -7355,7 +7355,7 @@ paths: required: true description: | The user session cookie for the - [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) + [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides @@ -7402,7 +7402,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7412,7 +7412,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. responses: '200': description: | @@ -7440,7 +7440,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7450,7 +7450,7 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. Specifies the task for the member. requestBody: description: | @@ -7487,7 +7487,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7501,7 +7501,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the member from.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from.' responses: '204': description: Success. The member is removed. @@ -7588,7 +7588,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. requestBody: description: | In the request body, provide an object that specifies the user. @@ -7651,7 +7651,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7659,7 +7659,7 @@ paths: schema: type: string required: true - description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task).' + description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task).' - in: path name: taskID schema: @@ -7667,7 +7667,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. responses: '204': description: Success. The owner is removed. @@ -8765,6 +8765,384 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: List authorizations + description: | + Lists authorizations. + + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### 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 + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization).' + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token](https://docs.influxdata.com/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. + responses: + '200': + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + post: + operationId: PostAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token). + + 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 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. + + - 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. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to + + #### Related guides + + - [Create a token](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + examples: + AuthorizationPostRequest: + summary: An authorization for a resource type + description: Creates an authorization. + value: + orgID: INFLUX_ORG_ID + description: iot_users read buckets + permissions: + - action: read + resource: + type: buckets + AuthorizationWithResourcePostRequest: + summary: An authorization for a resource + description: Creates an authorization for access to a specific resource. + value: + orgID: INFLUX_ORG_ID + description: iot_users read buckets + permissions: + - action: read + resource: + type: buckets + id: INFLUX_BUCKET_ID + AuthorizationWithUserPostRequest: + summary: An authorization scoped to a user + description: Creates an authorization scoped to a specific user. + value: + orgID: INFLUX_ORG_ID + userID: INFLUX_USER_ID + description: iot_user write to bucket + permissions: + - action: write + resource: + type: buckets + id: INFLUX_BUCKET_ID + responses: + '201': + description: | + Success. The authorization is created. The response body contains the + authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Retrieve an authorization + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + externalDocs: + url: 'https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/' + description: View tokens + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to retrieve. + responses: + '200': + description: Success. The response body contains the authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. + requestBody: + description: 'In the request body, provide the authorization properties to update.' + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to update. + responses: + '200': + description: Success. The response body contains the updated authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Delete an authorization + 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). + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to delete. + responses: + '204': + description: Success. The authorization is deleted. + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' components: parameters: TraceSpan: @@ -8787,7 +9165,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schema: type: integer minimum: 0 @@ -8827,7 +9205,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schemas: LanguageRequest: description: Flux query to be analyzed. @@ -8955,19 +9333,19 @@ components: properties: start: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. type: string format: date-time stop: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. type: string format: date-time predicate: description: | - An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string Node: @@ -9256,7 +9634,7 @@ components: value: type: boolean DateTimeLiteral: - description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp).' + description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp).' type: object properties: type: @@ -9356,7 +9734,7 @@ components: Dialect: description: | Options for tabular data output. - Default output is [annotated CSV](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) with headers. + Default output is [annotated CSV](https://docs.influxdata.com/influxdb/latest/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). @@ -9379,7 +9757,7 @@ components: #### Related guides - - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) for examples and more information. + - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/latest/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). @@ -9400,7 +9778,7 @@ components: dateTimeFormat: description: | The format for timestamps in results. - Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). + Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values @@ -9434,7 +9812,7 @@ components: type: string description: | The organization ID. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that the authorization is scoped to. + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the authorization is scoped to. permissions: type: array minItems: 1 @@ -9453,20 +9831,20 @@ components: description: | The API token. The token value is unique to the authorization. - [API tokens](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) are + [API tokens](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx` CLI commands--after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). userID: readOnly: true type: string - description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' + description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' user: readOnly: true type: string description: | The user name. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If the authorization is _scoped_ to a user, the user; otherwise, the creator of the authorization. org: @@ -9474,7 +9852,7 @@ components: type: string description: | The organization name. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the token is scoped to. links: type: object @@ -9537,7 +9915,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: @@ -9573,7 +9951,7 @@ components: [Retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. type: string default: '0' @@ -9677,7 +10055,7 @@ components: type: array description: | Retention rules to expire or retain data. - The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). #### InfluxDB Cloud @@ -9730,7 +10108,7 @@ components: type: integer format: int64 description: | - The [shard group duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#shard). + The [shard group duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud @@ -9739,11 +10117,11 @@ components: #### InfluxDB OSS - - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/#shard-group-duration). + - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). #### Related guides - - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/) + - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/) required: - everySeconds RetentionRule: @@ -9778,7 +10156,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -9812,7 +10190,7 @@ components: properties: time: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -9933,7 +10311,7 @@ components: The organization owns all resources created by the template. To find your organization, see how to - [view organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). + [view organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). stackID: type: string description: | @@ -9947,8 +10325,8 @@ components: #### Related guides - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [View stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/view/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [View stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/view/) template: type: object description: | @@ -10000,7 +10378,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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + For more examples, see how to [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -10009,7 +10387,7 @@ components: - `spec.associations.name` For more information about including environment references in template fields, see how to - [include user-definable resource names](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). + [include user-definable resource names](https://docs.influxdata.com/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names). additionalProperties: oneOf: - type: string @@ -10058,7 +10436,7 @@ components: #### Related guides - - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template) additionalProperties: type: string remotes: @@ -11030,7 +11408,7 @@ components: - success - canceled scheduledFor: - description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' + description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' type: string format: date-time log: @@ -11057,7 +11435,7 @@ components: example: '2006-01-02T15:04:05.999999999Z07:00' requestedAt: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -11083,7 +11461,7 @@ components: scheduledFor: nullable: true description: | - The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. type: string @@ -11096,17 +11474,17 @@ components: description: A description of the task. type: string TaskEvery: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string format: duration TaskFlux: description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) and the script for the task to run. #### Related guides - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) type: string format: Flux TaskName: @@ -11119,12 +11497,12 @@ components: TaskOrg: description: | An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskOrgID: description: | An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskStatusType: type: string @@ -13511,7 +13889,7 @@ components: type: string latestCompleted: type: string - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' format: date-time readOnly: true lastRunStatus: @@ -13781,7 +14159,7 @@ components: - endpointID properties: latestCompleted: - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true diff --git a/contracts/legacy.yml b/contracts/legacy.yml index 36c031482..591ceb189 100644 --- a/contracts/legacy.yml +++ b/contracts/legacy.yml @@ -520,18 +520,18 @@ components: properties: orgID: type: string - 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. userID: type: string - 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. token: type: string - description: A name that you provide for the authorization. + description: The name that you provide for the authorization. permissions: type: array minItems: 1 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' @@ -653,7 +653,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: diff --git a/contracts/oss-diff.yml b/contracts/oss-diff.yml index 1f634a0b0..81882661b 100644 --- a/contracts/oss-diff.yml +++ b/contracts/oss-diff.yml @@ -1341,332 +1341,6 @@ paths: default: description: Unexpected error $ref: '#/paths/~1config/get/responses/401' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - - Security and access endpoints - summary: List authorizations - description: | - Lists authorizations. - - 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 OSS returns - [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - - #### Required permissions - - - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - - #### Related guides - - - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: 'An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).' - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - type: object - properties: - links: - readOnly: true - $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' - authorizations: - type: array - items: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1config/get/responses/401' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token). - - 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 - - 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_DOCS_URL %}}/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. - - We recommend creating a generic user to create and manage tokens for writing data. - - #### Related guides - - - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - required: - - orgID - - permissions - allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' - - type: object - properties: - orgID: - type: string - description: | - An organization ID. - Specifies the organization that owns the authorization. - userID: - type: string - description: | - A user ID. - Specifies the user that the authorization is scoped to. - - When a user authenticates with username and password, - InfluxDB generates a _user session_ with all the permissions - specified by all the user's authorizations. - permissions: - type: array - minItems: 1 - description: | - A list of permissions for an authorization. - In the list, provide at least one `permission` object. - - In a `permission`, the `resource.type` property grants access to all - resources of the specified type. - To grant access to only a specific resource, specify the - `resource.id` property. - items: - required: - - action - - resource - properties: - action: - type: string - enum: - - read - - write - resource: - type: object - required: - - type - properties: - type: - type: string - enum: - - authorizations - - buckets - - dashboards - - orgs - - tasks - - telegrafs - - users - - variables - - secrets - - labels - - views - - documents - - notificationRules - - notificationEndpoints - - checks - - dbrp - - annotations - - sources - - scrapers - - notebooks - - remotes - - replications - - instance - - flows - - functions - - subscriptions - description: | - A resource type. - Identifies the API resource's type (or _kind_). - id: - type: string - description: | - A resource ID. - Identifies a specific resource. - name: - type: string - description: | - The name of the resource. - _Note: not all resource types have a `name` property_. - orgID: - type: string - description: | - An organization ID. - Identifies the organization that owns the resource. - org: - type: string - description: | - An organization name. - The organization that owns the resource. - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1config/get/responses/401' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - - Security and access endpoints - summary: Retrieve an authorization - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update an authorization to be active or inactive - requestBody: - description: Authorization to update - required: true - content: - application/json: - schema: - properties: - status: - description: 'Status of the token. If `inactive`, requests using the token will be rejected.' - default: active - type: string - enum: - - active - - inactive - description: - type: string - description: A description of the token. - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to update. - responses: - '200': - description: The active or inactive authorization - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' /variables: get: operationId: GetVariables @@ -5772,7 +5446,17 @@ components: - orgID - permissions allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' + - properties: + status: + description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + default: active + type: string + enum: + - active + - inactive + description: + type: string + description: A description of the token. - type: object properties: createdAt: @@ -5795,7 +5479,72 @@ components: The list of permissions. An authorization must have at least one permission. items: - $ref: '#/paths/~1authorizations/post/requestBody/content/application~1json/schema/allOf/1/properties/permissions/items' + required: + - action + - resource + properties: + action: + type: string + enum: + - read + - write + resource: + type: object + required: + - type + properties: + type: + type: string + enum: + - authorizations + - buckets + - dashboards + - orgs + - tasks + - telegrafs + - users + - variables + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + - annotations + - sources + - scrapers + - notebooks + - remotes + - replications + - instance + - flows + - functions + - subscriptions + description: | + A resource type. + Identifies the API resource's type (or _kind_). + id: + type: string + description: | + A resource ID. + Identifies a specific resource. + name: + type: string + description: | + The name of the resource. + _Note: not all resource types have a `name` property_. + orgID: + type: string + description: | + An organization ID. + Identifies the organization that owns the resource. + org: + type: string + description: | + An organization name. + The organization that owns the resource. id: readOnly: true type: string diff --git a/contracts/oss.json b/contracts/oss.json index 7810f447b..cc6ae2444 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -17,7 +17,7 @@ "tags": [ { "name": "Authorizations", - "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- InfluxDB allows access to the API token value immediately after the authorization is created.\n- You can’t change access (read/write) permissions for an API token after it’s created.\n- Tokens stop working when the user who created the token is deleted.\n\nAPI tokens are visible to the user who created the authorization and to any\nuser with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_.\nIn InfluxDB OSS, even if an API token has `read-authorizations` permission, the\ntoken can't be used to view its authorization details.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n#### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" + "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" }, { "name": "Buckets", @@ -41,15 +41,15 @@ }, { "name": "Tasks", - "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n#### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in a `task` object:\n\n\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n" + "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in a `task` object:\n\n\n\n### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n" }, { "name": "Templates", - "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for\neverything from dashboards and Telegraf to notifications and alerts.\nUse InfluxDB templates to quickly configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration with the\nInfluxData community.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n#### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" + "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for\neverything from dashboards and Telegraf to notifications and alerts.\nUse InfluxDB templates to quickly configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration with the\nInfluxData community.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" }, { "name": "Users", - "description": "Manage users for your organization.\nUsers are those with access to InfluxDB.\nTo grant a user permission to access data, add them as a member of an\norganization and provide them with an API token.\n\n#### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/)\n- [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)\n" + "description": "Manage users for your organization.\nUsers are those with access to InfluxDB.\nTo grant a user permission to access data, add them as a member of an\norganization and provide them with an API token.\n\n### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/)\n- [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)\n" }, { "name": "Write", @@ -83,7 +83,7 @@ { "name": "Pagination", "x-traitTag": true, - "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n| Query parameter | Value type | Description |\n|:------------------------ |:--------------------- |:-------------------------------------------|\n| `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n| `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n#### Limitations\n\n- For specific endpoint parameters and examples, see the endpoint definition.\n- If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" + "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n| Query parameter | Value type | Description |\n|:------------------------ |:--------------------- |:-------------------------------------------|\n| `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n| `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n### Limitations\n\n- For specific endpoint parameters and examples, see the endpoint definition.\n- If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" }, { "name": "Response codes", @@ -11208,6 +11208,370 @@ } } }, + "/authorizations": { + "get": { + "operationId": "GetAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "List authorizations", + "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\nTo retrieve an authorization, the request must use an API token that has the\nfollowing permissions:\n\n- `read-authorizations`\n- `read-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "query", + "name": "userID", + "schema": { + "type": "string" + }, + "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "user", + "schema": { + "type": "string" + }, + "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "orgID", + "schema": { + "type": "string" + }, + "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." + }, + { + "in": "query", + "name": "org", + "schema": { + "type": "string" + }, + "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + }, + { + "in": "query", + "name": "token", + "schema": { + "type": "string" + }, + "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nSpecifies an authorization by its `token` property value\nand returns the authorization.\n\n#### InfluxDB OSS\n\n- Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,\n applies other parameters, and then returns the result.\n\n#### Limitations\n\n- The parameter is non-repeatable. If you specify more than one,\n only the first one is used. If a resource with the specified\n property value doesn't exist, then the response body contains an empty list.\n" + } + ], + "responses": { + "200": { + "description": "Success. The response body contains a list of authorizations.\n\nIf the response body is missing authorizations that you expect, check that the API\ntoken used in the request has `read-user` permission for the users (`userID` property value)\nin those authorizations.\n\n#### InfluxDB OSS\n\n- **Warning**: The response body contains authorizations with their\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in clear text.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorizations" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "post": { + "operationId": "PostAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Create an authorization", + "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe API token is the authorization's `token` property value.\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n - InfluxDB allows access to the API token value immediately after the authorization is created.\n - You can’t change access (read/write) permissions for an API token after it’s created.\n - Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n - Create a generic user to create and manage tokens for writing data.\n - Store your tokens in a secure password vault for future access.\n\n#### Required permissions\n\n- `write-authorizations`\n- `write-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + } + ], + "requestBody": { + "description": "The authorization to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationPostRequest" + }, + "examples": { + "AuthorizationPostRequest": { + "$ref": "#/components/examples/AuthorizationPostRequest" + }, + "AuthorizationWithResourcePostRequest": { + "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" + }, + "AuthorizationWithUserPostRequest": { + "$ref": "#/components/examples/AuthorizationWithUserPostRequest" + } + } + } + } + }, + "responses": { + "201": { + "description": "Success. The authorization is created. The response body contains the\nauthorization.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, + "/authorizations/{authID}": { + "get": { + "operationId": "GetAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Retrieve an authorization", + "description": "Retrieves an authorization.\n\nUse this endpoint to retrieve information about an API token, including\nthe token's permissions and the user that the token is scoped to.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "externalDocs": { + "url": "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/", + "description": "View tokens" + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to retrieve." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "patch": { + "operationId": "PatchAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Update an API token to be active or inactive", + "description": "Updates an authorization.\n\nUse this endpoint to set an API token's status to be _active_ or _inactive_.\nInfluxDB rejects requests that use inactive API tokens.\n", + "requestBody": { + "description": "In the request body, provide the authorization properties to update.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationUpdateRequest" + } + } + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to update." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the updated authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "delete": { + "operationId": "DeleteAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Delete an authorization", + "description": "Deletes an authorization.\n\nUse the endpoint to delete an API token.\n\nIf you want to disable an API token instead of delete it,\n[update the authorization's status to `inactive`](#operation/PatchAuthorizationsID).\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to delete." + } + ], + "responses": { + "204": { + "description": "Success. The authorization is deleted." + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, "/debug/pprof/all": { "get": { "operationId": "GetDebugPprofAllProfiles", @@ -12468,259 +12832,6 @@ } } }, - "/authorizations": { - "get": { - "operationId": "GetAuthorizations", - "tags": [ - "Authorizations", - "Security and access endpoints" - ], - "summary": "List authorizations", - "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Required permissions\n\n- An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "query", - "name": "userID", - "schema": { - "type": "string" - }, - "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "user", - "schema": { - "type": "string" - }, - "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "orgID", - "schema": { - "type": "string" - }, - "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." - }, - { - "in": "query", - "name": "org", - "schema": { - "type": "string" - }, - "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" - } - ], - "responses": { - "200": { - "description": "Success. The response body contains a list of authorizations.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorizations" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "post": { - "operationId": "PostAuthorizations", - "tags": [ - "Authorizations" - ], - "summary": "Create an authorization", - "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe response contains the new authorization with the generated API token.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any\n user with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_.\n- You can't update an authorization's permissions.\n- Even if an API token has `read-authorizations` permission, the\n token can't be used to view its authorization details.\n- A token stops working when the user who created the authorization is deleted.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - } - ], - "requestBody": { - "description": "The authorization to create.", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationPostRequest" - }, - "examples": { - "AuthorizationPostRequest": { - "$ref": "#/components/examples/AuthorizationPostRequest" - }, - "AuthorizationWithResourcePostRequest": { - "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" - }, - "AuthorizationWithUserPostRequest": { - "$ref": "#/components/examples/AuthorizationWithUserPostRequest" - } - } - } - } - }, - "responses": { - "201": { - "description": "Success. The authorization is created. The response body contains the authorization.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/authorizations/{authID}": { - "get": { - "operationId": "GetAuthorizationsID", - "tags": [ - "Authorizations", - "Security and access endpoints" - ], - "summary": "Retrieve an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The ID of the authorization to get." - } - ], - "responses": { - "200": { - "description": "Authorization details", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "patch": { - "operationId": "PatchAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Update an authorization to be active or inactive", - "requestBody": { - "description": "Authorization to update", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationUpdateRequest" - } - } - } - }, - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The ID of the authorization to update." - } - ], - "responses": { - "200": { - "description": "The active or inactive authorization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "delete": { - "operationId": "DeleteAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Delete an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The ID of the authorization to delete." - } - ], - "responses": { - "204": { - "description": "Authorization deleted" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, "/variables": { "get": { "operationId": "GetVariables", @@ -16677,7 +16788,7 @@ "AuthorizationUpdateRequest": { "properties": { "status": { - "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.", "default": "active", "type": "string", "enum": [ diff --git a/contracts/oss.yml b/contracts/oss.yml index 0b4d47e4a..46bcf6092 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -18,28 +18,14 @@ 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](https://docs.influxdata.com/influxdb/v2.3/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_, the session carries the permissions granted by all the user's authorizations. - For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/). + For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/). To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints @@ -49,21 +35,21 @@ tags: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) - - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) - name: Buckets description: | - Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets - have a [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period), + have a [retention period](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) - name: Debug description: | Generate profiling and trace reports. @@ -84,7 +70,7 @@ tags: Delete data from an InfluxDB bucket. - name: Organizations description: | - Create and manage your [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Create and manage your [organizations](https://docs.influxdata.com/influxdb/latest/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. @@ -95,7 +81,7 @@ tags: Retrieve data, analyze queries, and get query suggestions. - name: Tasks description: | - Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the InfluxDB task engine. Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs. @@ -104,7 +90,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -112,10 +98,10 @@ tags: - #### Related guides + ### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Common data processing tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Common data processing tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) - name: Templates description: | Export and apply InfluxDB **templates**. @@ -136,10 +122,10 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - - [InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/) + - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) - name: Users description: | Manage users for your organization. @@ -147,20 +133,20 @@ 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](https://docs.influxdata.com/influxdb/v2.3/influxdb/latest/users/) - - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/v2.3/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) + - [Manage users](https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/) + - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) - name: Write description: | - Write time series data to [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Write time series data to [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). - name: Authentication description: | Use one of the following schemes to authenticate to the InfluxDB API: @@ -173,10 +159,10 @@ tags: - name: Quick start x-traitTag: true description: | - See the [**API Quick Start**](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/) + See the [**API Quick Start**](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. - [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/v2.3/api-guide/client-libraries/) + [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/latest/api-guide/client-libraries/) are available for popular languages and ready to import into your application. - name: Supported operations x-traitTag: true @@ -206,10 +192,10 @@ tags: | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| - | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | - | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | + | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | + | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | - name: Pagination x-traitTag: true description: | @@ -221,7 +207,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, @@ -293,7 +279,7 @@ paths: summary: Create a user session. description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user), + for a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the @@ -399,7 +385,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -444,7 +430,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -1291,7 +1277,7 @@ paths: description: | Writes data to a bucket. - Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud @@ -1326,12 +1312,12 @@ paths: #### Related guides - - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) requestBody: description: | - In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/). + In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/). To send compressed data, do the following: @@ -1341,7 +1327,7 @@ paths: #### Related guides - - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) + - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) required: true content: text/plain: @@ -1409,7 +1395,7 @@ paths: #### Related guides - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) schema: type: string description: Error content type. @@ -1484,7 +1470,7 @@ paths: #### Related guides - - [How to check for write errors](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [How to check for write errors](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) '400': description: | Bad request. The response body contains detail about the error. @@ -1642,8 +1628,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/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/). x-codeSamples: @@ -1669,8 +1655,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). required: true content: application/json: @@ -2563,7 +2549,7 @@ paths: summary: Generate a query Abstract Syntax Tree (AST) description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#abstract-syntax-tree-ast) + Tree (AST)](https://docs.influxdata.com/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query @@ -3896,7 +3882,7 @@ paths: #### Related guides - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/query-data/execute-queries/influx-api/) + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) parameters: - $ref: '#/components/parameters/TraceSpan' @@ -4027,9 +4013,9 @@ paths: description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#adjustable-service-quotas) + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#global-limits) + [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: @@ -4051,19 +4037,19 @@ paths: - Buckets summary: List buckets description: | - Lists [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Lists [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) associated with the authorization - ([API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token)). + ([API token](https://docs.influxdata.com/influxdb/latest/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`. #### InfluxDB OSS - - If you use an _[operator token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/#operator-token)_ + - If you use an _[operator token](https://docs.influxdata.com/influxdb/latest/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 @@ -4074,11 +4060,11 @@ paths: | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/v2.3/reference/internals/system-buckets/) | `read-orgs` | + | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - - [Manage buckets](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -4187,10 +4173,10 @@ paths: - Buckets summary: Create a bucket description: | - Creates a [bucket](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket) + Creates a [bucket](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket) and returns the bucket resource. The default data - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period) + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS @@ -4209,8 +4195,8 @@ paths: #### Related Guides - - [Create a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/bucket/create) + - [Create a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/bucket/create) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -4416,7 +4402,7 @@ paths: #### Related Guides - - [Update a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/update-bucket/) + - [Update a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/update-bucket/) requestBody: description: The bucket update to apply. required: true @@ -4562,7 +4548,7 @@ paths: #### Related Guides - - [Delete a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4648,7 +4634,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4712,7 +4698,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4838,18 +4824,18 @@ paths: description: | Lists all users for a bucket. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4908,18 +4894,18 @@ paths: description: | Add a user to a bucket and return the new user information. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4999,8 +4985,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5041,7 +5027,7 @@ paths: - Buckets summary: List all owners of a bucket description: | - Lists all [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Lists all [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) of a bucket. Bucket owners have permission to delete buckets and remove user and member @@ -5070,7 +5056,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5121,7 +5107,7 @@ paths: - Buckets summary: Add an owner to a bucket description: | - Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. @@ -5150,7 +5136,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5252,7 +5238,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5294,7 +5280,7 @@ paths: - Security and access endpoints summary: List organizations description: | - Lists [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization/). + Lists [organizations](https://docs.influxdata.com/influxdb/latest/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`. @@ -5305,7 +5291,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -5376,7 +5362,7 @@ paths: - Organizations summary: Create an organization description: | - Creates an [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Creates an [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud @@ -5385,7 +5371,7 @@ paths: #### Related guides - - [Manage organizations](https://docs.influxdata.com/influxdb/v2.3/organizations) + - [Manage organizations](https://docs.influxdata.com/influxdb/latest/organizations) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -5466,7 +5452,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5535,7 +5521,7 @@ paths: #### Related Guides - - [Update an organization](https://docs.influxdata.com/influxdb/v2.3/organizations/update-org/) + - [Update an organization](https://docs.influxdata.com/influxdb/latest/organizations/update-org/) requestBody: description: The organization update to apply. required: true @@ -5603,7 +5589,7 @@ paths: #### Related guides - - [Delete organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/delete-orgs/) + - [Delete organizations](https://docs.influxdata.com/influxdb/latest/organizations/delete-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5717,10 +5703,10 @@ paths: description: | Lists all users that belong to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5742,8 +5728,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5815,10 +5801,10 @@ paths: description: | Add a user to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5838,8 +5824,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5939,7 +5925,7 @@ paths: #### Related guides - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6122,7 +6108,7 @@ paths: - Security and access endpoints summary: Remove an owner from an organization description: | - Removes an [owner](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) from + Removes an [owner](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member @@ -6276,7 +6262,7 @@ paths: #### Related guides - - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/). + - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/). parameters: - in: query name: orgID @@ -6285,7 +6271,7 @@ paths: type: string description: | An organization ID. - Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). #### InfluxDB Cloud @@ -6394,8 +6380,8 @@ paths: #### Related guides - - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). + - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/init/). + - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). requestBody: description: The stack to create. required: true @@ -6590,8 +6576,8 @@ paths: summary: Apply or dry-run a template description: | Applies a template to - create or update a [stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) of InfluxDB - [resources](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/export/all/#resources). + create or update a [stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) of InfluxDB + [resources](https://docs.influxdata.com/influxdb/latest/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. @@ -6607,18 +6593,18 @@ paths: #### Custom values for templates - - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. + - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use - [secrets](https://docs.influxdata.com/influxdb/v2.3/security/secrets/). + [secrets](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template). + For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions @@ -6631,8 +6617,8 @@ paths: #### Related guides - - [Use templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/) - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) + - [Use templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) requestBody: required: true description: | @@ -6918,7 +6904,7 @@ paths: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. If you don't pass query parameters, InfluxDB returns all runs for the task @@ -6932,7 +6918,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to list runs for. - in: query name: after @@ -6954,7 +6940,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after the specified time. - in: query name: beforeTime @@ -6962,7 +6948,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before the specified time. responses: '200': @@ -7005,7 +6991,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to run. requestBody: content: @@ -7044,7 +7030,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -7056,7 +7042,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID @@ -7110,7 +7096,7 @@ paths: - Tasks summary: Cancel a running task description: | - Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to cancel a running task. @@ -7126,7 +7112,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to cancel. - in: path name: runID @@ -7177,7 +7163,7 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to retry and then returns the scheduled run. To manually start a _new_ task run, use the @@ -7200,7 +7186,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: @@ -7267,7 +7253,7 @@ paths: - Tasks summary: List logs for a task description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). When a task runs, InfluxDB creates a `run` record in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. @@ -7281,7 +7267,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve logs for.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for.' responses: '200': description: | @@ -7337,7 +7323,7 @@ paths: Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7345,7 +7331,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the run belongs to.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to.' - in: path name: runID schema: @@ -7442,7 +7428,7 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to add a label to a task. Labels are a way to add metadata to InfluxDB resources. @@ -7457,7 +7443,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. requestBody: description: | In the request body, provide an object that specifies the label. @@ -7490,7 +7476,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7500,7 +7486,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: @@ -7539,7 +7525,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](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -7548,7 +7534,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7596,7 +7582,7 @@ paths: - Users summary: Update a password description: | - Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/latest/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: @@ -7634,7 +7620,7 @@ paths: required: true description: | The user session cookie for the - [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) + [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides @@ -7681,7 +7667,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7691,7 +7677,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. responses: '200': description: | @@ -7719,7 +7705,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7729,7 +7715,7 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. Specifies the task for the member. requestBody: description: | @@ -7766,7 +7752,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7780,7 +7766,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the member from.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from.' responses: '204': description: Success. The member is removed. @@ -7867,7 +7853,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. requestBody: description: | In the request body, provide an object that specifies the user. @@ -7930,7 +7916,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7938,7 +7924,7 @@ paths: schema: type: string required: true - description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task).' + description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task).' - in: path name: taskID schema: @@ -7946,7 +7932,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. responses: '204': description: Success. The owner is removed. @@ -9044,6 +9030,357 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: List authorizations + description: | + Lists authorizations. + + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### 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 + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization).' + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token](https://docs.influxdata.com/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. + responses: + '200': + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + post: + operationId: PostAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token). + + 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 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. + + - 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. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to + + #### Related guides + + - [Create a token](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + examples: + AuthorizationPostRequest: + $ref: '#/components/examples/AuthorizationPostRequest' + AuthorizationWithResourcePostRequest: + $ref: '#/components/examples/AuthorizationWithResourcePostRequest' + AuthorizationWithUserPostRequest: + $ref: '#/components/examples/AuthorizationWithUserPostRequest' + responses: + '201': + description: | + Success. The authorization is created. The response body contains the + authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Retrieve an authorization + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + externalDocs: + url: 'https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/' + description: View tokens + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to retrieve. + responses: + '200': + description: Success. The response body contains the authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. + requestBody: + description: 'In the request body, provide the authorization properties to update.' + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to update. + responses: + '200': + description: Success. The response body contains the updated authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Delete an authorization + 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). + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to delete. + responses: + '204': + description: Success. The authorization is deleted. + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' /debug/pprof/all: get: operationId: GetDebugPprofAllProfiles @@ -9057,7 +9394,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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration) value. + Include by passing the `cpu` query parameter with a [duration](https://docs.influxdata.com/influxdb/latest/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 @@ -9106,7 +9443,7 @@ paths: - in: query name: cpu description: | - Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration). + Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration). schema: type: string format: duration @@ -9824,9 +10161,9 @@ paths: #### Related guides - - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/v2.3/reference/internals/metrics/). - - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/scrape-prometheus-metrics/). - - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/v2.3/reference/prometheus-metrics/). + - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/latest/reference/internals/metrics/). + - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/scrape-prometheus-metrics/). + - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/latest/reference/prometheus-metrics/). servers: - url: '' parameters: @@ -9894,7 +10231,7 @@ paths: - Users summary: List users description: | - Lists [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Lists [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). Default limit is `20`. To limit which users are returned, pass query parameters in your request. @@ -9922,14 +10259,14 @@ paths: type: string description: | A user name. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). - in: query name: id schema: type: string description: | A user ID. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). responses: '200': description: Success. The response contains a list of `users`. @@ -9974,7 +10311,7 @@ paths: - Users summary: Create a user description: | - Creates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that can access InfluxDB. + Creates a [user](https://docs.influxdata.com/influxdb/latest/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 @@ -10090,11 +10427,11 @@ paths: - Users summary: Retrieve a user description: | - Retrieves a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -10104,7 +10441,7 @@ paths: required: true description: | A user ID. - Retrieves the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). responses: '200': description: Success. The response body contains the user. @@ -10121,7 +10458,7 @@ paths: - Users summary: Update a user description: | - Updates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) and returns the user. + Updates a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) and returns the user. #### Required permissions @@ -10133,7 +10470,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) requestBody: description: 'In the request body, provide the user properties to update.' required: true @@ -10150,7 +10487,7 @@ paths: required: true description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to update. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to update. responses: '200': description: | @@ -10176,7 +10513,7 @@ paths: - Users summary: Delete a user description: | - Deletes a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Deletes a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Required permissions @@ -10188,7 +10525,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -10198,7 +10535,7 @@ paths: required: true description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to delete. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to delete. responses: '204': description: Success. The user is deleted. @@ -10258,216 +10595,6 @@ paths: default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - - Security and access endpoints - summary: List authorizations - description: | - Lists authorizations. - - 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 OSS returns - [API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - - #### Required permissions - - - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - - #### Related guides - - - [View tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/view-tokens/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization).' - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token). - - 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 - - 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](https://docs.influxdata.com/influxdb/v2.3/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. - - We recommend creating a generic user to create and manage tokens for writing data. - - #### Related guides - - - [Create a token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPostRequest' - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - - Security and access endpoints - summary: Retrieve an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update an authorization to be active or inactive - requestBody: - description: Authorization to update - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to update. - responses: - '200': - description: The active or inactive authorization - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' /variables: get: operationId: GetVariables @@ -11363,7 +11490,7 @@ paths: description: The shard ID. - in: query name: since - description: 'The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) to include in the snapshot.' + description: 'The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) to include in the snapshot.' schema: type: string format: date-time @@ -11619,7 +11746,7 @@ paths: #### Related guides - - [View your runtime server configuration](https://docs.influxdata.com/influxdb/v2.3/reference/config-options/#view-your-runtime-server-configuration) + - [View your runtime server configuration](https://docs.influxdata.com/influxdb/latest/reference/config-options/#view-your-runtime-server-configuration) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -11973,11 +12100,11 @@ paths: - Dashboards summary: List dashboards description: | - Lists [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Lists [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). #### Related guides - - [Manage dashboards](https://docs.influxdata.com/influxdb/v2.3/visualize-data/dashboards/). + - [Manage dashboards](https://docs.influxdata.com/influxdb/latest/visualize-data/dashboards/). parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -11985,7 +12112,7 @@ paths: - $ref: '#/components/parameters/Descending' - in: query name: owner - description: 'A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) where the specified user has the `owner` role.' + description: 'A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) where the specified user has the `owner` role.' schema: type: string - in: query @@ -12001,7 +12128,7 @@ paths: name: id description: | A list of dashboard IDs. - Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). If you specify `id` and `owner`, only `id` is used. schema: type: array @@ -12011,16 +12138,16 @@ paths: name: orgID description: | An organization ID. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). schema: type: string - in: query name: org description: | An organization name. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). schema: type: string responses: @@ -12044,21 +12171,21 @@ paths: - Tasks summary: List tasks description: | - Lists [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/process-data/) + - [Process data with InfluxDB tasks](https://docs.influxdata.com/influxdb/latest/process-data/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: name description: | A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified name. Different tasks may have the same name. schema: @@ -12069,29 +12196,29 @@ paths: type: string description: | A task ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) created after the specified task. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) created after the specified task. - in: query name: user schema: type: string description: | A user ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) - owned by the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) + owned by the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). - in: query name: org schema: type: string description: | An organization name. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). - in: query name: orgID schema: type: string description: | An organization ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). required: true - in: query name: status @@ -12102,7 +12229,7 @@ paths: - inactive description: | A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that have the specified status. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified status. - in: query name: limit schema: @@ -12111,7 +12238,7 @@ paths: maximum: 500 default: 100 description: | - The maximum number of [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to return. + The maximum number of [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. @@ -12121,7 +12248,7 @@ paths: name: type description: | A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) in the response. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the response. Default is `system`. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). @@ -12226,16 +12353,16 @@ paths: - Tasks summary: Create a task description: | - Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a script. #### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Create a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/create-task/) - - [Common tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Create a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/create-task/) + - [Common tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -12301,7 +12428,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -12311,7 +12438,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve. responses: '200': description: Success. The response body contains the task. @@ -12335,7 +12462,7 @@ paths: - Tasks summary: Update a task description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task), + Updates the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. @@ -12343,8 +12470,8 @@ paths: #### Related guides - - [Update a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Update a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) requestBody: description: | In the request body, provide the task properties to update. @@ -12365,7 +12492,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task)to update. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task)to update. responses: '200': description: Success. The response body contains the updated task. @@ -12389,7 +12516,7 @@ paths: - Tasks summary: Delete a task description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Deletes the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. @@ -12405,7 +12532,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete. responses: '204': description: Success. The task and runs are deleted. Scheduled runs are canceled. @@ -12441,7 +12568,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schema: type: integer minimum: 0 @@ -12481,7 +12608,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schemas: LanguageRequest: description: Flux query to be analyzed. @@ -12609,19 +12736,19 @@ components: properties: start: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. type: string format: date-time stop: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. type: string format: date-time predicate: description: | - An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string Node: @@ -12910,7 +13037,7 @@ components: value: type: boolean DateTimeLiteral: - description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp).' + description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp).' type: object properties: type: @@ -13010,7 +13137,7 @@ components: Dialect: description: | Options for tabular data output. - Default output is [annotated CSV](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) with headers. + Default output is [annotated CSV](https://docs.influxdata.com/influxdb/latest/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). @@ -13033,7 +13160,7 @@ components: #### Related guides - - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) for examples and more information. + - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/latest/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). @@ -13054,7 +13181,7 @@ components: dateTimeFormat: description: | The format for timestamps in results. - Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). + Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values @@ -13088,7 +13215,7 @@ components: type: string description: | The organization ID. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that the authorization is scoped to. + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the authorization is scoped to. permissions: type: array minItems: 1 @@ -13107,20 +13234,20 @@ components: description: | The API token. The token value is unique to the authorization. - [API tokens](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) are + [API tokens](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx` CLI commands--after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). userID: readOnly: true type: string - description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' + description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' user: readOnly: true type: string description: | The user name. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If the authorization is _scoped_ to a user, the user; otherwise, the creator of the authorization. org: @@ -13128,7 +13255,7 @@ components: type: string description: | The organization name. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the token is scoped to. links: type: object @@ -13191,7 +13318,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: @@ -13227,7 +13354,7 @@ components: [Retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. type: string default: '0' @@ -13331,7 +13458,7 @@ components: type: array description: | Retention rules to expire or retain data. - The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). #### InfluxDB Cloud @@ -13384,7 +13511,7 @@ components: type: integer format: int64 description: | - The [shard group duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#shard). + The [shard group duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud @@ -13393,11 +13520,11 @@ components: #### InfluxDB OSS - - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/#shard-group-duration). + - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). #### Related guides - - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/) + - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/) required: - everySeconds RetentionRule: @@ -13432,7 +13559,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -13466,7 +13593,7 @@ components: properties: time: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -13587,7 +13714,7 @@ components: The organization owns all resources created by the template. To find your organization, see how to - [view organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). + [view organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). stackID: type: string description: | @@ -13601,8 +13728,8 @@ components: #### Related guides - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [View stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/view/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [View stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/view/) template: type: object description: | @@ -13654,7 +13781,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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + For more examples, see how to [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -13663,7 +13790,7 @@ components: - `spec.associations.name` For more information about including environment references in template fields, see how to - [include user-definable resource names](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). + [include user-definable resource names](https://docs.influxdata.com/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names). additionalProperties: oneOf: - type: string @@ -13712,7 +13839,7 @@ components: #### Related guides - - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template) additionalProperties: type: string remotes: @@ -14684,7 +14811,7 @@ components: - success - canceled scheduledFor: - description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' + description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' type: string format: date-time log: @@ -14711,7 +14838,7 @@ components: example: '2006-01-02T15:04:05.999999999Z07:00' requestedAt: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -14737,7 +14864,7 @@ components: scheduledFor: nullable: true description: | - The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. type: string @@ -14750,17 +14877,17 @@ components: description: A description of the task. type: string TaskEvery: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string format: duration TaskFlux: description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) and the script for the task to run. #### Related guides - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) type: string format: Flux TaskName: @@ -14773,12 +14900,12 @@ components: TaskOrg: description: | An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskOrgID: description: | An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskStatusType: type: string @@ -17165,7 +17292,7 @@ components: type: string latestCompleted: type: string - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' format: date-time readOnly: true lastRunStatus: @@ -17435,7 +17562,7 @@ components: - endpointID properties: latestCompleted: - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true @@ -18622,7 +18749,7 @@ components: ownerID: description: | A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the task. + Identifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the task. To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to @@ -18650,7 +18777,7 @@ components: offset: $ref: '#/components/schemas/TaskOffset' latestCompleted: - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true @@ -18897,7 +19024,7 @@ components: Replace the following: - *`INFLUX_URL`*: your InfluxDB URL - - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) ### Related endpoints @@ -18905,8 +19032,8 @@ components: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) BasicAuthentication: type: http scheme: basic @@ -18935,7 +19062,7 @@ components: In the examples, replace the following: - **`USERNAME`**: InfluxDB username - - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) - **`INFLUX_URL`**: your InfluxDB URL #### Encode credentials with cURL diff --git a/contracts/priv/cloud-priv.yml b/contracts/priv/cloud-priv.yml index cd90b87d7..ccc061595 100644 --- a/contracts/priv/cloud-priv.yml +++ b/contracts/priv/cloud-priv.yml @@ -883,7 +883,7 @@ components: allOf: - properties: status: - 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.' default: active type: string enum: diff --git a/contracts/ref/cloud.yml b/contracts/ref/cloud.yml index b855849b4..974c7cfac 100644 --- a/contracts/ref/cloud.yml +++ b/contracts/ref/cloud.yml @@ -387,8 +387,8 @@ 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 @@ -2380,22 +2380,23 @@ 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: @@ -6752,7 +6753,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 @@ -6762,7 +6763,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 @@ -6772,39 +6777,46 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + - description: An organization ID. Only returns authorizations that belong to + the specified [organization](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). in: query name: org schema: type: string - description: | An API [token](https://docs.influxdata.com/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: @@ -6815,7 +6827,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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6829,6 +6853,8 @@ paths: summary: List authorizations tags: - Authorizations + - API tokens + - Security and access endpoints post: description: | Creates an authorization and returns the authorization with the @@ -6836,20 +6862,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 @@ -6878,7 +6908,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 @@ -6892,12 +6923,21 @@ paths: summary: Create an authorization tags: - 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 @@ -6905,18 +6945,71 @@ 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 + - 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/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 @@ -6928,19 +7021,57 @@ 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 + - 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 @@ -6951,7 +7082,8 @@ 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": @@ -6959,13 +7091,15 @@ 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 + - API tokens + - Security and access endpoints /api/v2/buckets: get: description: | @@ -18429,24 +18563,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_, @@ -18494,7 +18616,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](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -18523,7 +18645,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -18531,7 +18653,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/cloud/process-data/get-started/) - [Common data processing tasks](https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/) @@ -18554,7 +18676,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/) @@ -18569,14 +18691,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](https://docs.influxdata.com/influxdb/cloud/organizations/users/) name: Users @@ -18651,7 +18773,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, diff --git a/contracts/ref/oss.yml b/contracts/ref/oss.yml index 350b92605..b86a92fe3 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -53,7 +53,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). in: query name: after required: false @@ -82,7 +82,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). in: query name: offset required: false @@ -372,8 +372,8 @@ 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 @@ -844,7 +844,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true @@ -1290,7 +1290,7 @@ components: type: object DateTimeLiteral: description: Represents an instant in time with nanosecond precision in [RFC3339Nano - date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp). + date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp). properties: type: $ref: '#/components/schemas/NodeType' @@ -1357,18 +1357,18 @@ components: properties: predicate: description: | - An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string start: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. format: date-time type: string stop: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. format: date-time type: string @@ -1379,7 +1379,7 @@ components: Dialect: description: | Options for tabular data output. - Default output is [annotated CSV](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) with headers. + Default output is [annotated CSV](https://docs.influxdata.com/influxdb/latest/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). @@ -1391,7 +1391,7 @@ components: #### Related guides - - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) for examples and more information. + - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/latest/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). @@ -1414,7 +1414,7 @@ components: default: RFC3339 description: | The format for timestamps in results. - Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). + Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values @@ -2399,22 +2399,23 @@ 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: @@ -2616,7 +2617,7 @@ components: readOnly: true type: string time: - description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) + description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time @@ -2957,7 +2958,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true @@ -3307,7 +3308,7 @@ components: type: integer shardGroupDurationSeconds: description: | - The [shard group duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#shard). + The [shard group duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud @@ -3316,11 +3317,11 @@ components: #### InfluxDB OSS - - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/#shard-group-duration). + - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). #### Related guides - - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/) + - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/) format: int64 type: integer type: @@ -3451,7 +3452,7 @@ components: [Retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. type: string schemaType: @@ -3984,7 +3985,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -3998,7 +3999,7 @@ components: RetentionRules: description: | Retention rules to expire or retain data. - The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). #### InfluxDB Cloud @@ -4148,14 +4149,14 @@ components: readOnly: true type: array requestedAt: - description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) + description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + description: The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. format: date-time type: string @@ -4182,7 +4183,7 @@ components: properties: scheduledFor: description: | - The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. format: date-time @@ -4919,7 +4920,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true @@ -4958,7 +4959,7 @@ components: ownerID: description: | A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the task. + Identifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the task. To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to @@ -5003,19 +5004,19 @@ components: description: A description of the task. type: string TaskEvery: - description: The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: The interval ([duration literal](https://docs.influxdata.com/influxdb/latest/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 TaskFlux: description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) and the script for the task to run. #### Related guides - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) format: Flux type: string TaskName: @@ -5030,12 +5031,12 @@ components: TaskOrg: description: | An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskOrgID: description: | An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskStatusType: description: | @@ -5350,7 +5351,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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + For more examples, see how to [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -5359,7 +5360,7 @@ components: - `spec.associations.name` For more information about including environment references in template fields, see how to - [include user-definable resource names](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). + [include user-definable resource names](https://docs.influxdata.com/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names). type: object orgID: description: | @@ -5368,7 +5369,7 @@ components: The organization owns all resources created by the template. To find your organization, see how to - [view organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). + [view organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). type: string remotes: description: | @@ -5429,7 +5430,7 @@ components: #### Related guides - - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template) type: object stackID: description: | @@ -5443,8 +5444,8 @@ components: #### Related guides - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [View stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/view/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [View stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/view/) type: string template: description: | @@ -6694,7 +6695,7 @@ components: In the examples, replace the following: - **`USERNAME`**: InfluxDB username - - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) - **`INFLUX_URL`**: your InfluxDB URL #### Encode credentials with cURL @@ -6764,7 +6765,7 @@ components: Replace the following: - *`INFLUX_URL`*: your InfluxDB URL - - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) ### Related endpoints @@ -6772,8 +6773,8 @@ components: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) in: header name: Authorization type: apiKey @@ -6816,57 +6817,91 @@ 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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. #### Required permissions - - An _[operator token](https://docs.influxdata.com/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 - - [View tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/view-tokens/) + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) operationId: GetAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: user schema: type: string - description: An organization ID. Only returns authorizations that belong to - the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: org schema: type: string + - description: | + An API [token](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6880,33 +6915,37 @@ paths: summary: List authorizations tags: - Authorizations + - API tokens - Security and access endpoints post: description: | Creates an authorization and returns the authorization with the - generated API [token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token). + generated API [token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token). 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](https://docs.influxdata.com/influxdb/v2.3/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 the following for managing your tokens: - We recommend creating a generic user to create and manage tokens for writing data. + - 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 - - [Create a token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) + - [Create a token](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) operationId: PostAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' @@ -6931,7 +6970,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 @@ -6945,12 +6985,21 @@ paths: summary: Create an authorization tags: - 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 @@ -6958,18 +7007,71 @@ 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 + - 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/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 @@ -6981,19 +7083,57 @@ 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 + - 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 @@ -7004,7 +7144,8 @@ 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": @@ -7012,13 +7153,15 @@ 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 + - API tokens + - Security and access endpoints /api/v2/backup/kv: get: deprecated: true @@ -7110,7 +7253,7 @@ paths: schema: format: int64 type: integer - - description: The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + - description: The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) to include in the snapshot. examples: RFC3339: @@ -7156,19 +7299,19 @@ paths: /api/v2/buckets: get: description: | - Lists [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Lists [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) associated with the authorization - ([API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token)). + ([API token](https://docs.influxdata.com/influxdb/latest/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`. #### InfluxDB OSS - - If you use an _[operator token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/#operator-token)_ + - If you use an _[operator token](https://docs.influxdata.com/influxdb/latest/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 @@ -7179,11 +7322,11 @@ paths: | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/v2.3/reference/internals/system-buckets/) | `read-orgs` | + | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - - [Manage buckets](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) operationId: GetBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7292,10 +7435,10 @@ paths: --header "Content-Type: application/json" post: description: | - Creates a [bucket](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket) + Creates a [bucket](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket) and returns the bucket resource. The default data - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period) + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS @@ -7314,8 +7457,8 @@ paths: #### Related Guides - - [Create a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/bucket/create) + - [Create a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/bucket/create) operationId: PostBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7452,7 +7595,7 @@ paths: #### Related Guides - - [Delete a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) operationId: DeleteBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7615,7 +7758,7 @@ paths: #### Related Guides - - [Update a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/update-bucket/) + - [Update a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/update-bucket/) operationId: PatchBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7754,7 +7897,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) operationId: GetBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7818,7 +7961,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) operationId: PostBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7944,18 +8087,18 @@ paths: description: | Lists all users for a bucket. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: GetBucketsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8014,18 +8157,18 @@ paths: description: | Add a user to a bucket and return the new user information. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: PostBucketsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8105,8 +8248,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: DeleteBucketsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8147,7 +8290,7 @@ paths: /api/v2/buckets/{bucketID}/owners: get: description: | - Lists all [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Lists all [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) of a bucket. Bucket owners have permission to delete buckets and remove user and member @@ -8176,7 +8319,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) operationId: GetBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8227,7 +8370,7 @@ paths: - Buckets post: description: | - Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. @@ -8256,7 +8399,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) operationId: PostBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8358,7 +8501,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) operationId: DeleteBucketsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8727,7 +8870,7 @@ paths: #### Related guides - - [View your runtime server configuration](https://docs.influxdata.com/influxdb/v2.3/reference/config-options/#view-your-runtime-server-configuration) + - [View your runtime server configuration](https://docs.influxdata.com/influxdb/latest/reference/config-options/#view-your-runtime-server-configuration) operationId: GetConfig parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8751,18 +8894,18 @@ paths: /api/v2/dashboards: get: description: | - Lists [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Lists [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). #### Related guides - - [Manage dashboards](https://docs.influxdata.com/influxdb/v2.3/visualize-data/dashboards/). + - [Manage dashboards](https://docs.influxdata.com/influxdb/latest/visualize-data/dashboards/). operationId: GetDashboards parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Descending' - - description: A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) + - description: A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) where the specified user has the `owner` role. in: query name: owner @@ -8779,7 +8922,7 @@ paths: type: string - description: | A list of dashboard IDs. - Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). If you specify `id` and `owner`, only `id` is used. in: query name: id @@ -8789,16 +8932,16 @@ paths: type: array - description: | An organization ID. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: org schema: @@ -9735,7 +9878,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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration) value. + Include by passing the `cpu` query parameter with a [duration](https://docs.influxdata.com/influxdb/latest/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 @@ -9745,7 +9888,7 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration). + Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration). in: query name: cpu schema: @@ -10506,8 +10649,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/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 @@ -10584,8 +10727,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). required: true responses: "204": @@ -10662,7 +10805,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](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -10671,7 +10814,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10898,7 +11041,7 @@ paths: /api/v2/me/password: put: description: | - Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/latest/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: @@ -10930,7 +11073,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | The user session cookie for the - [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) + [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides @@ -10985,9 +11128,9 @@ paths: #### Related guides - - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/v2.3/reference/internals/metrics/). - - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/scrape-prometheus-metrics/). - - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/v2.3/reference/prometheus-metrics/). + - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/latest/reference/internals/metrics/). + - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/scrape-prometheus-metrics/). + - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/latest/reference/prometheus-metrics/). operationId: GetMetrics parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11653,7 +11796,7 @@ paths: /api/v2/orgs: get: description: | - Lists [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization/). + Lists [organizations](https://docs.influxdata.com/influxdb/latest/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`. @@ -11664,7 +11807,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) operationId: GetOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11736,7 +11879,7 @@ paths: - Security and access endpoints post: description: | - Creates an [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Creates an [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud @@ -11745,7 +11888,7 @@ paths: #### Related guides - - [Manage organizations](https://docs.influxdata.com/influxdb/v2.3/organizations) + - [Manage organizations](https://docs.influxdata.com/influxdb/latest/organizations) operationId: PostOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11843,7 +11986,7 @@ paths: #### Related guides - - [Delete organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/delete-orgs/) + - [Delete organizations](https://docs.influxdata.com/influxdb/latest/organizations/delete-orgs/) operationId: DeleteOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11902,7 +12045,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11972,7 +12115,7 @@ paths: #### Related Guides - - [Update an organization](https://docs.influxdata.com/influxdb/v2.3/organizations/update-org/) + - [Update an organization](https://docs.influxdata.com/influxdb/latest/organizations/update-org/) operationId: PatchOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12019,10 +12162,10 @@ paths: description: | Lists all users that belong to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -12044,8 +12187,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: GetOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12118,10 +12261,10 @@ paths: description: | Add a user to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -12141,8 +12284,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: PostOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12241,7 +12384,7 @@ paths: #### Related guides - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: DeleteOrgsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12424,7 +12567,7 @@ paths: /api/v2/orgs/{orgID}/owners/{userID}: delete: description: | - Removes an [owner](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) from + Removes an [owner](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member @@ -12615,7 +12758,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) operationId: GetPing responses: "204": @@ -12660,7 +12803,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) operationId: HeadPing responses: "204": @@ -12704,7 +12847,7 @@ paths: #### Related guides - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/query-data/execute-queries/influx-api/) + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) operationId: PostQuery parameters: @@ -12828,9 +12971,9 @@ paths: description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#adjustable-service-quotas) + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#global-limits) + [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: @@ -13017,7 +13160,7 @@ paths: post: description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#abstract-syntax-tree-ast) + Tree (AST)](https://docs.influxdata.com/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query @@ -15211,7 +15354,7 @@ paths: post: description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user), + for a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the @@ -15539,12 +15682,12 @@ paths: #### Related guides - - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/). + - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/). operationId: ListStacks parameters: - description: | An organization ID. - Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). #### InfluxDB Cloud @@ -15659,8 +15802,8 @@ paths: #### Related guides - - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). + - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/init/). + - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). operationId: CreateStack requestBody: content: @@ -15854,20 +15997,20 @@ paths: /api/v2/tasks: get: description: | - Lists [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/process-data/) + - [Process data with InfluxDB tasks](https://docs.influxdata.com/influxdb/latest/process-data/) operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified name. Different tasks may have the same name. in: query @@ -15876,29 +16019,29 @@ paths: type: string - description: | A task ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) created after the specified task. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) created after the specified task. in: query name: after schema: type: string - description: | A user ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) - owned by the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) + owned by the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: user schema: type: string - description: | An organization name. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: org schema: type: string - description: | An organization ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: orgID required: true @@ -15906,7 +16049,7 @@ paths: type: string - description: | A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that have the specified status. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified status. in: query name: status schema: @@ -15915,7 +16058,7 @@ paths: - inactive type: string - description: | - The maximum number of [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to return. + The maximum number of [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. @@ -15930,7 +16073,7 @@ paths: type: integer - description: | A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) in the response. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the response. Default is `system`. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). @@ -16036,16 +16179,16 @@ paths: --header 'Authorization: Token INFLUX_API_TOKEN' post: description: | - Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a script. #### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Create a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/create-task/) - - [Common tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Create a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/create-task/) + - [Common tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) operationId: PostTasks parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16113,7 +16256,7 @@ paths: /api/v2/tasks/{taskID}: delete: description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Deletes the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. @@ -16125,7 +16268,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete. in: path name: taskID required: true @@ -16150,13 +16293,13 @@ paths: - Tasks get: description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve. in: path name: taskID required: true @@ -16185,7 +16328,7 @@ paths: - Tasks patch: description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task), + Updates the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. @@ -16193,14 +16336,14 @@ paths: #### Related guides - - [Update a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Update a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task)to update. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task)to update. in: path name: taskID required: true @@ -16280,7 +16423,7 @@ paths: - Tasks post: description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to add a label to a task. Labels are a way to add metadata to InfluxDB resources. @@ -16291,7 +16434,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. in: path name: taskID required: true @@ -16328,13 +16471,13 @@ paths: /api/v2/tasks/{taskID}/labels/{labelID}: delete: description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. in: path name: taskID required: true @@ -16367,7 +16510,7 @@ paths: /api/v2/tasks/{taskID}/logs: get: description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). When a task runs, InfluxDB creates a `run` record in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. @@ -16377,7 +16520,7 @@ paths: operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for. in: path name: taskID @@ -16446,13 +16589,13 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. in: path name: taskID required: true @@ -16484,13 +16627,13 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. Specifies the task for the member. in: path name: taskID @@ -16531,7 +16674,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16541,7 +16684,7 @@ paths: required: true schema: type: string - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from. in: path name: taskID @@ -16629,7 +16772,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. in: path name: taskID required: true @@ -16696,11 +16839,11 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). in: path name: userID required: true @@ -16708,7 +16851,7 @@ paths: type: string - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. in: path name: taskID required: true @@ -16729,7 +16872,7 @@ paths: /api/v2/tasks/{taskID}/runs: get: description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. If you don't pass query parameters, InfluxDB returns all runs for the task @@ -16739,7 +16882,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to list runs for. in: path name: taskID @@ -16762,7 +16905,7 @@ paths: minimum: 1 type: integer - description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after the specified time. in: query name: afterTime @@ -16770,7 +16913,7 @@ paths: format: date-time type: string - description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before the specified time. in: query name: beforeTime @@ -16812,7 +16955,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to run. in: path name: taskID @@ -16856,7 +16999,7 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}: delete: description: | - Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to cancel a running task. @@ -16868,7 +17011,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to cancel. in: path name: taskID @@ -16922,7 +17065,7 @@ paths: - Tasks get: description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. operationId: GetTasksIDRunsID @@ -16930,7 +17073,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. in: path name: taskID @@ -16995,11 +17138,11 @@ paths: Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to. in: path name: taskID @@ -17069,7 +17212,7 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}/retry: post: description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to retry and then returns the scheduled run. To manually start a _new_ task run, use the @@ -17083,7 +17226,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. in: path name: taskID required: true @@ -17617,8 +17760,8 @@ paths: post: description: | Applies a template to - create or update a [stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) of InfluxDB - [resources](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/export/all/#resources). + create or update a [stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) of InfluxDB + [resources](https://docs.influxdata.com/influxdb/latest/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. @@ -17634,18 +17777,18 @@ paths: #### Custom values for templates - - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. + - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use - [secrets](https://docs.influxdata.com/influxdb/v2.3/security/secrets/). + [secrets](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template). + For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions @@ -17658,8 +17801,8 @@ paths: #### Related guides - - [Use templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/) - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) + - [Use templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) operationId: ApplyTemplate requestBody: content: @@ -17948,7 +18091,7 @@ paths: /api/v2/users: get: description: | - Lists [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Lists [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). Default limit is `20`. To limit which users are returned, pass query parameters in your request. @@ -17973,14 +18116,14 @@ paths: - $ref: '#/components/parameters/After' - description: | A user name. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: name schema: type: string - description: | A user ID. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: id schema: @@ -18029,7 +18172,7 @@ paths: - Users post: description: | - Creates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that can access InfluxDB. + Creates a [user](https://docs.influxdata.com/influxdb/latest/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 @@ -18144,7 +18287,7 @@ paths: /api/v2/users/{userID}: delete: description: | - Deletes a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Deletes a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Required permissions @@ -18156,13 +18299,13 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) operationId: DeleteUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to delete. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to delete. in: path name: userID required: true @@ -18191,17 +18334,17 @@ paths: - Users get: description: | - Retrieves a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) operationId: GetUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Retrieves the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: path name: userID required: true @@ -18223,7 +18366,7 @@ paths: - Users patch: description: | - Updates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) and returns the user. + Updates a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) and returns the user. #### Required permissions @@ -18235,13 +18378,13 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) operationId: PatchUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to update. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to update. in: path name: userID required: true @@ -18691,7 +18834,7 @@ paths: description: | Writes data to a bucket. - Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud @@ -18726,9 +18869,9 @@ paths: #### Related guides - - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) operationId: PostWrite parameters: - $ref: '#/components/parameters/TraceSpan' @@ -18784,7 +18927,7 @@ paths: #### Related guides - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) in: header name: Accept schema: @@ -18857,7 +19000,7 @@ paths: format: byte type: string description: | - In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/). + In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/). To send compressed data, do the following: @@ -18867,7 +19010,7 @@ paths: #### Related guides - - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) + - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) required: true responses: "204": @@ -18885,7 +19028,7 @@ paths: #### Related guides - - [How to check for write errors](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [How to check for write errors](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) "400": content: application/json: @@ -19527,28 +19670,14 @@ 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](https://docs.influxdata.com/influxdb/v2.3/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_, the session carries the permissions granted by all the user's authorizations. - For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/). + For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/). To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints @@ -19558,21 +19687,21 @@ tags: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) - - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) name: Authorizations - description: | - Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets - have a [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period), + have a [retention period](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) name: Buckets - description: | Generate profiling and trace reports. @@ -19593,7 +19722,7 @@ tags: Delete data from an InfluxDB bucket. name: Delete - description: | - Create and manage your [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Create and manage your [organizations](https://docs.influxdata.com/influxdb/latest/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. @@ -19604,7 +19733,7 @@ tags: Retrieve data, analyze queries, and get query suggestions. name: Query - description: | - Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the InfluxDB task engine. Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs. @@ -19613,7 +19742,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -19621,10 +19750,10 @@ tags: - #### Related guides + ### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Common data processing tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Common data processing tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) name: Tasks - description: | Export and apply InfluxDB **templates**. @@ -19645,10 +19774,10 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - - [InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/) + - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) name: Templates - description: | Manage users for your organization. @@ -19656,20 +19785,20 @@ 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](https://docs.influxdata.com/influxdb/v2.3/influxdb/latest/users/) - - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/v2.3/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) + - [Manage users](https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/) + - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) name: Users - description: | - Write time series data to [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Write time series data to [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). name: Write - description: | Use one of the following schemes to authenticate to the InfluxDB API: @@ -19681,10 +19810,10 @@ tags: name: Authentication x-traitTag: true - description: | - See the [**API Quick Start**](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/) + See the [**API Quick Start**](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. - [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/v2.3/api-guide/client-libraries/) + [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/latest/api-guide/client-libraries/) are available for popular languages and ready to import into your application. name: Quick start x-traitTag: true @@ -19724,10 +19853,10 @@ tags: | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| - | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | - | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | + | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | + | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | name: Common parameters x-traitTag: true - description: | @@ -19739,7 +19868,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, diff --git a/scripts/generate.sh b/scripts/generate.sh index 1f9d54748..d7b227dcd 100755 --- a/scripts/generate.sh +++ b/scripts/generate.sh @@ -2,7 +2,6 @@ CONTRACTS=${CONTRACTS:-contracts} INFLUXDB_DOCS_URL=https://docs.influxdata.com/influxdb -OSS_VERSION=v2.3 mkdir -p $CONTRACTS @@ -14,7 +13,7 @@ sed -e '/#REF_COMMON_PARAMETERS/{r ./src/common/_parameters.yml' -e 'd}' | sed -e '/#REF_COMMON_RESPONSES/{r ./src/common/_responses.yml' -e 'd}' | sed -e '/#REF_COMMON_SCHEMAS/{r ./src/common/_schemas.yml' -e 'd}' > src/.oss_gen.yml && \ swagger-cli bundle src/.oss_gen.yml --type yaml | \ -(sed -e "s|{{% INFLUXDB_DOCS_URL %}}|${INFLUXDB_DOCS_URL}/${OSS_VERSION}|g" > ${CONTRACTS}/oss.yml) && \ +(sed -e "s|{{% INFLUXDB_DOCS_URL %}}|${INFLUXDB_DOCS_URL}/latest|g" > ${CONTRACTS}/oss.yml) && \ swagger-cli bundle ${CONTRACTS}/oss.yml --outfile ${CONTRACTS}/oss.yml --type yaml swagger-cli bundle src/.oss_gen.yml --outfile ${CONTRACTS}/oss.json --type json && \ rm src/.oss_gen.yml @@ -38,7 +37,7 @@ sed -e '/#REF_COMMON_PARAMETERS/{r ./src/common/_parameters.yml' -e 'd}' | sed -e '/#REF_COMMON_RESPONSES/{r ./src/common/_responses.yml' -e 'd}' | sed -e '/#REF_COMMON_SCHEMAS/{r ./src/common/_schemas.yml' -e 'd}' > src/.common_gen.yml && \ swagger-cli bundle src/.common_gen.yml --type yaml | \ -(sed -e "s|{{% INFLUXDB_DOCS_URL %}}|${INFLUXDB_DOCS_URL}/${OSS_VERSION}|g" > ${CONTRACTS}/common.yml) && \ +(sed -e "s|{{% INFLUXDB_DOCS_URL %}}|${INFLUXDB_DOCS_URL}/latest|g" > ${CONTRACTS}/common.yml) && \ swagger-cli bundle ${CONTRACTS}/common.yml --outfile ${CONTRACTS}/common.yml --type yaml rm src/.common_gen.yml diff --git a/src/cloud.yml b/src/cloud.yml index 329549154..ee3d12d30 100644 --- a/src/cloud.yml +++ b/src/cloud.yml @@ -21,10 +21,6 @@ paths: $ref: './cloud/paths/setup.yml' /setup/user: $ref: './cloud/paths/setup_user.yml' - /authorizations: - $ref: './cloud/paths/authorizations.yml' - /authorizations/{authID}: - $ref: './cloud/paths/authorizations_authID.yml' /variables: $ref: './cloud/paths/variables.yml' '/variables/{variableID}': diff --git a/src/cloud/paths/authorizations.yml b/src/cloud/paths/authorizations.yml deleted file mode 100644 index eb20d6ac9..000000000 --- a/src/cloud/paths/authorizations.yml +++ /dev/null @@ -1,145 +0,0 @@ -get: - operationId: GetAuthorizations - tags: - - Authorizations - summary: List authorizations - description: | - 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. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - - `read-authorizations` - - #### Related guides - - - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: | - An organization ID. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value. - Returns the authorization for the specified token. - responses: - "200": - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - $ref: "../../common/schemas/Authorizations.yml" - "400": - description: Invalid request - $ref: '../../common/responses/ServerError.yml' - "401": - $ref: "../../common/responses/AuthorizationError.yml" - "500": - $ref: "../../common/responses/InternalServerError.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' -post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token). - - 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 - - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud 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. - - 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. - - #### Related guides - - - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - $ref: "../../common/schemas/AuthorizationPostRequest.yml" - examples: - AuthorizationPostRequest: - $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationPostRequest" - AuthorizationWithResourcePostRequest: - $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithResourcePostRequest" - AuthorizationWithUserPostRequest: - $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithUserPostRequest" - responses: - "201": - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: "../../common/schemas/Authorization.yml" - "400": - description: Invalid request - $ref: '../../common/responses/ServerError.yml' - "401": - $ref: "../../common/responses/AuthorizationError.yml" - "500": - $ref: "../../common/responses/InternalServerError.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' diff --git a/src/cloud/paths/authorizations_authID.yml b/src/cloud/paths/authorizations_authID.yml deleted file mode 100644 index c85317bfb..000000000 --- a/src/cloud/paths/authorizations_authID.yml +++ /dev/null @@ -1,73 +0,0 @@ -get: - operationId: GetAuthorizationsID - tags: - - Authorizations - summary: Retrieve an authorization - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to get. - responses: - "200": - description: Authorization details - content: - application/json: - schema: - $ref: "../../common/schemas/Authorization.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' -patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update authorization status - description: Update an authorization's status to `active` or `inactive`. - requestBody: - description: The updated Authorization object. - required: true - content: - application/json: - schema: - $ref: "../../common/schemas/AuthorizationUpdateRequest.yml" - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to update. - responses: - "200": - description: The updated authorization. - content: - application/json: - schema: - $ref: "../../common/schemas/Authorization.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' -delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to delete. - responses: - "204": - description: Authorization deleted - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' diff --git a/src/cloud/tags.yml b/src/cloud/tags.yml index e37e5b34c..9b09776f6 100644 --- a/src/cloud/tags.yml +++ b/src/cloud/tags.yml @@ -7,24 +7,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_, @@ -72,7 +60,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_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -101,7 +89,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -109,7 +97,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/) - [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/) @@ -132,7 +120,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/) - [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/) @@ -147,14 +135,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_DOCS_URL %}}/organizations/users/) - name: Write @@ -235,7 +223,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, diff --git a/src/common/_paths.yml b/src/common/_paths.yml index 6f21ef6b9..3d9dcfd8d 100644 --- a/src/common/_paths.yml +++ b/src/common/_paths.yml @@ -174,3 +174,7 @@ $ref: "./common/paths/notificationEndpoints_endpointID_labels.yml" "/notificationEndpoints/{endpointID}/labels/{labelID}": $ref: "./common/paths/notificationEndpoints_endpointID_labels_labelID.yml" + /authorizations: + $ref: "./common/paths/authorizations.yml" + /authorizations/{authID}: + $ref: "./common/paths/authorizations_authID.yml" diff --git a/src/common/paths/authorizations.yml b/src/common/paths/authorizations.yml index 53491a4fd..1a8fabea9 100644 --- a/src/common/paths/authorizations.yml +++ b/src/common/paths/authorizations.yml @@ -2,6 +2,7 @@ get: operationId: GetAuthorizations tags: - Authorizations + - API tokens - Security and access endpoints summary: List authorizations description: | @@ -10,16 +11,19 @@ get: 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_DOCS_URL %}}/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. + - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. #### Required permissions - - An _[operator token](https://docs.influxdata.com/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 @@ -54,9 +58,40 @@ get: description: | An organization name. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token]({{% INFLUXDB_DOCS_URL %}}/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. responses: "200": - 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_DOCS_URL %}}/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. content: application/json: schema: @@ -75,6 +110,8 @@ post: operationId: PostAuthorizations tags: - Authorizations + - API tokens + - Security and access endpoints summary: Create an authorization description: | Creates an authorization and returns the authorization with the @@ -82,21 +119,24 @@ post: 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_DOCS_URL %}}/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 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 - We recommend creating a generic user to create and manage tokens for writing data. + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to #### Related guides @@ -120,7 +160,8 @@ post: responses: "201": description: | - Success. The authorization is created. The response body contains the authorization. + Success. The authorization is created. The response body contains the + authorization. content: application/json: schema: diff --git a/src/common/paths/authorizations_authID.yml b/src/common/paths/authorizations_authID.yml index 768e62822..9ddcfc44d 100644 --- a/src/common/paths/authorizations_authID.yml +++ b/src/common/paths/authorizations_authID.yml @@ -2,8 +2,28 @@ get: operationId: GetAuthorizationsID tags: - Authorizations + - API tokens - Security and access endpoints summary: Retrieve an authorization + 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_DOCS_URL %}}/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) + externalDocs: + url: "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/" + description: View tokens parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -11,14 +31,48 @@ get: schema: type: string required: true - description: The ID of the authorization to get. + description: An authorization ID. Specifies the authorization to retrieve. responses: "200": - description: Authorization details + description: Success. The response body contains the authorization. content: application/json: schema: $ref: "../../common/schemas/Authorization.yml" + "400": + description: | + Bad request. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + "401": + $ref: "../responses/AuthorizationError.yml" + "404": + description: | + Not found. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: { + "code": "not found", + "message": "authorization not found" + } + "500": + $ref: "../responses/InternalServerError.yml" default: description: Unexpected error $ref: '../../common/responses/ServerError.yml' @@ -26,9 +80,16 @@ patch: operationId: PatchAuthorizationsID tags: - Authorizations - summary: Update an authorization to be active or inactive + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. requestBody: - description: Authorization to update + description: In the request body, provide the authorization properties to update. required: true content: application/json: @@ -41,10 +102,10 @@ patch: schema: type: string required: true - description: The ID of the authorization to update. + description: An authorization ID. Specifies the authorization to update. responses: "200": - description: The active or inactive authorization + description: Success. The response body contains the updated authorization. content: application/json: schema: @@ -56,7 +117,16 @@ delete: operationId: DeleteAuthorizationsID tags: - Authorizations + - API tokens + - Security and access endpoints summary: Delete an authorization + 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). parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -64,10 +134,44 @@ delete: schema: type: string required: true - description: The ID of the authorization to delete. + description: An authorization ID. Specifies the authorization to delete. responses: "204": - description: Authorization deleted + description: Success. The authorization is deleted. + "400": + description: | + Bad request. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + "401": + $ref: "../responses/AuthorizationError.yml" + "404": + description: | + Not found. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: { + "code": "not found", + "message": "authorization not found" + } + "500": + $ref: "../responses/InternalServerError.yml" default: description: Unexpected error $ref: '../../common/responses/ServerError.yml' diff --git a/src/common/schemas/AuthorizationUpdateRequest.yml b/src/common/schemas/AuthorizationUpdateRequest.yml index 598a251a4..c07b46ce1 100644 --- a/src/common/schemas/AuthorizationUpdateRequest.yml +++ b/src/common/schemas/AuthorizationUpdateRequest.yml @@ -1,6 +1,6 @@ properties: status: - 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. default: active type: string enum: diff --git a/src/legacy/schemas/LegacyAuthorizationPostRequest.yml b/src/legacy/schemas/LegacyAuthorizationPostRequest.yml index 5b572add1..818c5a012 100644 --- a/src/legacy/schemas/LegacyAuthorizationPostRequest.yml +++ b/src/legacy/schemas/LegacyAuthorizationPostRequest.yml @@ -5,18 +5,18 @@ allOf: properties: orgID: type: string - 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. userID: type: string - 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. token: type: string - description: A name that you provide for the authorization. + description: The name that you provide for the authorization. permissions: type: array minItems: 1 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: "../../common/schemas/Permission.yml" diff --git a/src/oss.yml b/src/oss.yml index f325a28a9..b4596b0d5 100644 --- a/src/oss.yml +++ b/src/oss.yml @@ -45,10 +45,6 @@ paths: $ref: "./common/paths/users_userID.yml" /setup: $ref: "./common/paths/setup.yml" - /authorizations: - $ref: "./common/paths/authorizations.yml" - /authorizations/{authID}: - $ref: "./common/paths/authorizations_authID.yml" /variables: $ref: "./common/paths/variables.yml" "/variables/{variableID}": diff --git a/src/oss/tags.yml b/src/oss/tags.yml index 5879b2864..fe6c356b5 100644 --- a/src/oss/tags.yml +++ b/src/oss/tags.yml @@ -7,23 +7,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_DOCS_URL %}}/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_, @@ -93,7 +79,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -101,7 +87,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/) - [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/) @@ -125,7 +111,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/) - [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/) @@ -136,14 +122,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_DOCS_URL %}}/influxdb/latest/users/) - [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) @@ -225,7 +211,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, From 7cd3420fd98eb2c67f36938ea5805d5b2346e8ff Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 8 Nov 2022 10:25:58 -0600 Subject: [PATCH 2/2] refactor: authorizations. --- contracts/cloud-diff.yml | 415 ++----- contracts/cloud.json | 638 +++++----- contracts/cloud.yml | 601 ++++++---- contracts/common.yml | 674 ++++++++--- contracts/legacy.yml | 10 +- contracts/oss-diff.yml | 405 ++----- contracts/oss.json | 629 ++++++---- contracts/oss.yml | 1045 +++++++++-------- contracts/priv/cloud-priv.yml | 2 +- contracts/ref/cloud.yml | 238 +++- contracts/ref/oss.yml | 695 ++++++----- src/cloud.yml | 4 - src/cloud/paths/authorizations.yml | 145 --- src/cloud/paths/authorizations_authID.yml | 73 -- src/cloud/tags.yml | 28 +- src/common/_paths.yml | 4 + src/common/paths/authorizations.yml | 77 +- src/common/paths/authorizations_authID.yml | 120 +- .../schemas/AuthorizationUpdateRequest.yml | 2 +- .../LegacyAuthorizationPostRequest.yml | 8 +- src/oss.yml | 4 - src/oss/tags.yml | 28 +- 22 files changed, 3160 insertions(+), 2685 deletions(-) delete mode 100644 src/cloud/paths/authorizations.yml delete mode 100644 src/cloud/paths/authorizations_authID.yml diff --git a/contracts/cloud-diff.yml b/contracts/cloud-diff.yml index f19781072..1f86f43bb 100644 --- a/contracts/cloud-diff.yml +++ b/contracts/cloud-diff.yml @@ -426,342 +426,6 @@ paths: default: description: Unexpected error $ref: '#/paths/~1tasks/get/responses/default' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - summary: List authorizations - description: | - 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. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - - `read-authorizations` - - #### Related guides - - - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: | - An organization ID. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value. - Returns the authorization for the specified token. - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - type: object - properties: - links: - readOnly: true - $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' - authorizations: - type: array - items: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1tasks/get/responses/default' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token). - - 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 - - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud 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. - - 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. - - #### Related guides - - - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - required: - - orgID - - permissions - allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' - - type: object - properties: - orgID: - type: string - description: | - An organization ID. - Specifies the organization that owns the authorization. - userID: - type: string - description: | - A user ID. - Specifies the user that the authorization is scoped to. - - When a user authenticates with username and password, - InfluxDB generates a _user session_ with all the permissions - specified by all the user's authorizations. - permissions: - type: array - minItems: 1 - description: | - A list of permissions for an authorization. - In the list, provide at least one `permission` object. - - In a `permission`, the `resource.type` property grants access to all - resources of the specified type. - To grant access to only a specific resource, specify the - `resource.id` property. - items: - required: - - action - - resource - properties: - action: - type: string - enum: - - read - - write - resource: - type: object - required: - - type - properties: - type: - type: string - enum: - - authorizations - - buckets - - dashboards - - orgs - - tasks - - telegrafs - - users - - variables - - secrets - - labels - - views - - documents - - notificationRules - - notificationEndpoints - - checks - - dbrp - - annotations - - sources - - scrapers - - notebooks - - remotes - - replications - - instance - - flows - - functions - - subscriptions - description: | - A resource type. - Identifies the API resource's type (or _kind_). - id: - type: string - description: | - A resource ID. - Identifies a specific resource. - name: - type: string - description: | - The name of the resource. - _Note: not all resource types have a `name` property_. - orgID: - type: string - description: | - An organization ID. - Identifies the organization that owns the resource. - org: - type: string - description: | - An organization name. - The organization that owns the resource. - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1tasks/get/responses/default' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - summary: Retrieve an authorization - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update authorization status - description: Update an authorization's status to `active` or `inactive`. - requestBody: - description: The updated Authorization object. - required: true - content: - application/json: - schema: - properties: - status: - description: 'Status of the token. If `inactive`, requests using the token will be rejected.' - default: active - type: string - enum: - - active - - inactive - description: - type: string - description: A description of the token. - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to update. - responses: - '200': - description: The updated authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/paths/~1users/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/paths/~1tasks/get/responses/default' /variables: get: operationId: GetVariables @@ -4039,7 +3703,17 @@ components: - orgID - permissions allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' + - properties: + status: + description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + default: active + type: string + enum: + - active + - inactive + description: + type: string + description: A description of the token. - type: object properties: createdAt: @@ -4062,7 +3736,72 @@ components: The list of permissions. An authorization must have at least one permission. items: - $ref: '#/paths/~1authorizations/post/requestBody/content/application~1json/schema/allOf/1/properties/permissions/items' + required: + - action + - resource + properties: + action: + type: string + enum: + - read + - write + resource: + type: object + required: + - type + properties: + type: + type: string + enum: + - authorizations + - buckets + - dashboards + - orgs + - tasks + - telegrafs + - users + - variables + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + - annotations + - sources + - scrapers + - notebooks + - remotes + - replications + - instance + - flows + - functions + - subscriptions + description: | + A resource type. + Identifies the API resource's type (or _kind_). + id: + type: string + description: | + A resource ID. + Identifies a specific resource. + name: + type: string + description: | + The name of the resource. + _Note: not all resource types have a `name` property_. + orgID: + type: string + description: | + An organization ID. + Identifies the organization that owns the resource. + org: + type: string + description: | + An organization name. + The organization that owns the resource. id: readOnly: true type: string diff --git a/contracts/cloud.json b/contracts/cloud.json index 9640cc831..efa67d9c1 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -17,7 +17,7 @@ "tags": [ { "name": "Authorizations", - "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nIn InfluxDB Cloud, an authorization with `read-authorizations` permission\ncan be used to view other authorizations.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- InfluxDB allows access to the API token value immediately after the authorization is created.\n- You can’t change access (read/write) permissions for an API token after it’s created.\n- Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n#### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf the user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" + "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf the user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" }, { "name": "Buckets", @@ -25,7 +25,7 @@ }, { "name": "Invokable Scripts", - "description": "Store, manage, and execute scripts in InfluxDB.\nA script stores your custom Flux script and provides an invokable\nendpoint that accepts runtime parameters.\nIn a script, you can specify custom runtime parameters\n(`params`)--for example, `params.myparameter`.\nOnce you create a script, InfluxDB generates an\n[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)\nfor your organization.\nYou can run the script from API requests and tasks, defining parameter\nvalues for each run.\nWhen the script runs, InfluxDB replaces `params` references in the\nscript with the runtime parameter values you define.\n\nUse the `/api/v2/scripts` endpoints to create and manage scripts.\nSee related guides to learn how to define parameters and execute scripts.\n\n#### Related guides\n\n- [Invoke custom scripts]({{% INFLUXDB_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests.\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n" + "description": "Store, manage, and execute scripts in InfluxDB.\nA script stores your custom Flux script and provides an invokable\nendpoint that accepts runtime parameters.\nIn a script, you can specify custom runtime parameters\n(`params`)--for example, `params.myparameter`.\nOnce you create a script, InfluxDB generates an\n[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)\nfor your organization.\nYou can run the script from API requests and tasks, defining parameter\nvalues for each run.\nWhen the script runs, InfluxDB replaces `params` references in the\nscript with the runtime parameter values you define.\n\nUse the `/api/v2/scripts` endpoints to create and manage scripts.\nSee related guides to learn how to define parameters and execute scripts.\n\n### Related guides\n\n- [Invoke custom scripts]({{% INFLUXDB_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests.\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n" }, { "name": "Delete", @@ -41,15 +41,15 @@ }, { "name": "Tasks", - "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n#### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in this object:\n\n\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Create a script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script)\n" + "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in this object:\n\n\n\n### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Create a script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script)\n" }, { "name": "Templates", - "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for resources.\nUse InfluxDB templates to configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n#### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" + "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for resources.\nUse InfluxDB templates to configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" }, { "name": "Users", - "description": "Retrieve specific users.\n\nInfluxDB Cloud lets you invite and collaborate with multiple users in your organization.\nTo invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);\nyou can't use the InfluxDB API to manage users in InfluxDB Cloud.\nOnce a user is added to your organization, you can use the\n`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to\nview specific members.\n\n#### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n" + "description": "Retrieve specific users.\n\nInfluxDB Cloud lets you invite and collaborate with multiple users in your organization.\nTo invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);\nyou can't use the InfluxDB API to manage users in InfluxDB Cloud.\nOnce a user is added to your organization, you can use the\n`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to\nview specific members.\n\n### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n" }, { "name": "Write", @@ -83,7 +83,7 @@ { "name": "Pagination", "x-traitTag": true, - "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n | Query parameter | Value type | Description |\n |:------------------------ |:--------------------- |:-------------------------------------------|\n | `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n | `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n #### Limitations\n\n - For specific endpoint parameters and examples, see the endpoint definition.\n - If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" + "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n | Query parameter | Value type | Description |\n |:------------------------ |:--------------------- |:-------------------------------------------|\n | `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n | `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n ### Limitations\n\n - For specific endpoint parameters and examples, see the endpoint definition.\n - If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" }, { "name": "Response codes", @@ -11207,6 +11207,370 @@ } } }, + "/authorizations": { + "get": { + "operationId": "GetAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "List authorizations", + "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\nTo retrieve an authorization, the request must use an API token that has the\nfollowing permissions:\n\n- `read-authorizations`\n- `read-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "query", + "name": "userID", + "schema": { + "type": "string" + }, + "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "user", + "schema": { + "type": "string" + }, + "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "orgID", + "schema": { + "type": "string" + }, + "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." + }, + { + "in": "query", + "name": "org", + "schema": { + "type": "string" + }, + "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + }, + { + "in": "query", + "name": "token", + "schema": { + "type": "string" + }, + "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nSpecifies an authorization by its `token` property value\nand returns the authorization.\n\n#### InfluxDB OSS\n\n- Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,\n applies other parameters, and then returns the result.\n\n#### Limitations\n\n- The parameter is non-repeatable. If you specify more than one,\n only the first one is used. If a resource with the specified\n property value doesn't exist, then the response body contains an empty list.\n" + } + ], + "responses": { + "200": { + "description": "Success. The response body contains a list of authorizations.\n\nIf the response body is missing authorizations that you expect, check that the API\ntoken used in the request has `read-user` permission for the users (`userID` property value)\nin those authorizations.\n\n#### InfluxDB OSS\n\n- **Warning**: The response body contains authorizations with their\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in clear text.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorizations" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "post": { + "operationId": "PostAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Create an authorization", + "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe API token is the authorization's `token` property value.\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n - InfluxDB allows access to the API token value immediately after the authorization is created.\n - You can’t change access (read/write) permissions for an API token after it’s created.\n - Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n - Create a generic user to create and manage tokens for writing data.\n - Store your tokens in a secure password vault for future access.\n\n#### Required permissions\n\n- `write-authorizations`\n- `write-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + } + ], + "requestBody": { + "description": "The authorization to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationPostRequest" + }, + "examples": { + "AuthorizationPostRequest": { + "$ref": "#/components/examples/AuthorizationPostRequest" + }, + "AuthorizationWithResourcePostRequest": { + "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" + }, + "AuthorizationWithUserPostRequest": { + "$ref": "#/components/examples/AuthorizationWithUserPostRequest" + } + } + } + } + }, + "responses": { + "201": { + "description": "Success. The authorization is created. The response body contains the\nauthorization.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, + "/authorizations/{authID}": { + "get": { + "operationId": "GetAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Retrieve an authorization", + "description": "Retrieves an authorization.\n\nUse this endpoint to retrieve information about an API token, including\nthe token's permissions and the user that the token is scoped to.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "externalDocs": { + "url": "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/", + "description": "View tokens" + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to retrieve." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "patch": { + "operationId": "PatchAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Update an API token to be active or inactive", + "description": "Updates an authorization.\n\nUse this endpoint to set an API token's status to be _active_ or _inactive_.\nInfluxDB rejects requests that use inactive API tokens.\n", + "requestBody": { + "description": "In the request body, provide the authorization properties to update.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationUpdateRequest" + } + } + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to update." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the updated authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "delete": { + "operationId": "DeleteAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Delete an authorization", + "description": "Deletes an authorization.\n\nUse the endpoint to delete an API token.\n\nIf you want to disable an API token instead of delete it,\n[update the authorization's status to `inactive`](#operation/PatchAuthorizationsID).\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to delete." + } + ], + "responses": { + "204": { + "description": "Success. The authorization is deleted." + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, "/users": { "get": { "operationId": "GetUsers", @@ -11587,266 +11951,6 @@ } } }, - "/authorizations": { - "get": { - "operationId": "GetAuthorizations", - "tags": [ - "Authorizations" - ], - "summary": "List authorizations", - "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations for the organization.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\n- `read-authorizations`\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "query", - "name": "userID", - "schema": { - "type": "string" - }, - "description": "A user ID.\nOnly returns authorizations scoped to the specified\n[user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "user", - "schema": { - "type": "string" - }, - "description": "A user name.\nOnly returns authorizations scoped to the specified\n[user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "orgID", - "schema": { - "type": "string" - }, - "description": "An organization ID.\nOnly returns authorizations that belong to the specified\n[organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" - }, - { - "in": "query", - "name": "org", - "schema": { - "type": "string" - }, - "description": "An organization name.\nOnly returns authorizations that belong to the specified\n[organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" - }, - { - "in": "query", - "name": "token", - "schema": { - "type": "string" - }, - "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nReturns the authorization for the specified token.\n" - } - ], - "responses": { - "200": { - "description": "Success. The response body contains a list of authorizations.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorizations" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "post": { - "operationId": "PostAuthorizations", - "tags": [ - "Authorizations" - ], - "summary": "Create an authorization", - "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB Cloud enforces access restrictions on API tokens.\n\n- InfluxDB only allows access to the API token value immediately after the authorization is created.\n- You can't update an authorization's permissions.\n- A token stops working when the user who created the authorization is deleted.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - } - ], - "requestBody": { - "description": "The authorization to create.", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationPostRequest" - }, - "examples": { - "AuthorizationPostRequest": { - "$ref": "#/components/examples/AuthorizationPostRequest" - }, - "AuthorizationWithResourcePostRequest": { - "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" - }, - "AuthorizationWithUserPostRequest": { - "$ref": "#/components/examples/AuthorizationWithUserPostRequest" - } - } - } - } - }, - "responses": { - "201": { - "description": "Success. The authorization is created. The response body contains the authorization.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/authorizations/{authID}": { - "get": { - "operationId": "GetAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Retrieve an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The identifier of the authorization to get." - } - ], - "responses": { - "200": { - "description": "Authorization details", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "patch": { - "operationId": "PatchAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Update authorization status", - "description": "Update an authorization's status to `active` or `inactive`.", - "requestBody": { - "description": "The updated Authorization object.", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationUpdateRequest" - } - } - } - }, - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The identifier of the authorization to update." - } - ], - "responses": { - "200": { - "description": "The updated authorization.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "delete": { - "operationId": "DeleteAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Delete an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The identifier of the authorization to delete." - } - ], - "responses": { - "204": { - "description": "Authorization deleted" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, "/variables": { "get": { "operationId": "GetVariables", @@ -14300,7 +14404,7 @@ "AuthorizationUpdateRequest": { "properties": { "status": { - "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.", "default": "active", "type": "string", "enum": [ diff --git a/contracts/cloud.yml b/contracts/cloud.yml index ea80266e5..cd0d75901 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -18,24 +18,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_, @@ -83,7 +71,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](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -112,7 +100,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -120,7 +108,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/cloud/process-data/get-started/) - [Common data processing tasks](https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/) @@ -143,7 +131,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/) @@ -158,14 +146,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](https://docs.influxdata.com/influxdb/cloud/organizations/users/) - name: Write @@ -231,7 +219,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, @@ -9054,6 +9042,357 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: List authorizations + description: | + Lists authorizations. + + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### 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 + + - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization).' + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token](https://docs.influxdata.com/influxdb/cloud/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. + responses: + '200': + 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + post: + operationId: PostAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token). + + 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 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. + + - 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. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to + + #### Related guides + + - [Create a token](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + examples: + AuthorizationPostRequest: + $ref: '#/components/examples/AuthorizationPostRequest' + AuthorizationWithResourcePostRequest: + $ref: '#/components/examples/AuthorizationWithResourcePostRequest' + AuthorizationWithUserPostRequest: + $ref: '#/components/examples/AuthorizationWithUserPostRequest' + responses: + '201': + description: | + Success. The authorization is created. The response body contains the + authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Retrieve an authorization + 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) + externalDocs: + url: 'https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/' + description: View tokens + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to retrieve. + responses: + '200': + description: Success. The response body contains the authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. + requestBody: + description: 'In the request body, provide the authorization properties to update.' + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to update. + responses: + '200': + description: Success. The response body contains the updated authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Delete an authorization + 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). + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to delete. + responses: + '204': + description: Success. The authorization is deleted. + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' /users: get: operationId: GetUsers @@ -9416,226 +9755,6 @@ paths: default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - summary: List authorizations - description: | - 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. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - - `read-authorizations` - - #### Related guides - - - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: | - An organization ID. - Only returns authorizations that belong to the specified - [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified - [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) value. - Returns the authorization for the specified token. - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token). - - 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 - - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud 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. - - 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. - - #### Related guides - - - [Create a token](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPostRequest' - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - summary: Retrieve an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update authorization status - description: Update an authorization's status to `active` or `inactive`. - requestBody: - description: The updated Authorization object. - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to update. - responses: - '200': - description: The updated authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' /variables: get: operationId: GetVariables @@ -11615,7 +11734,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: diff --git a/contracts/common.yml b/contracts/common.yml index dcf366600..8f4ab8c9c 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -14,7 +14,7 @@ paths: summary: Create a user session. description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user), + for a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the @@ -120,7 +120,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -165,7 +165,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -1012,7 +1012,7 @@ paths: description: | Writes data to a bucket. - Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud @@ -1047,12 +1047,12 @@ paths: #### Related guides - - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) requestBody: description: | - In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/). + In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/). To send compressed data, do the following: @@ -1062,7 +1062,7 @@ paths: #### Related guides - - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) + - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) required: true content: text/plain: @@ -1130,7 +1130,7 @@ paths: #### Related guides - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) schema: type: string description: Error content type. @@ -1205,7 +1205,7 @@ paths: #### Related guides - - [How to check for write errors](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [How to check for write errors](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) '400': description: | Bad request. The response body contains detail about the error. @@ -1363,8 +1363,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/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/). x-codeSamples: @@ -1390,8 +1390,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). required: true content: application/json: @@ -2284,7 +2284,7 @@ paths: summary: Generate a query Abstract Syntax Tree (AST) description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#abstract-syntax-tree-ast) + Tree (AST)](https://docs.influxdata.com/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query @@ -3617,7 +3617,7 @@ paths: #### Related guides - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/query-data/execute-queries/influx-api/) + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3748,9 +3748,9 @@ paths: description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#adjustable-service-quotas) + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#global-limits) + [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: @@ -3772,19 +3772,19 @@ paths: - Buckets summary: List buckets description: | - Lists [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Lists [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) associated with the authorization - ([API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token)). + ([API token](https://docs.influxdata.com/influxdb/latest/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`. #### InfluxDB OSS - - If you use an _[operator token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/#operator-token)_ + - If you use an _[operator token](https://docs.influxdata.com/influxdb/latest/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 @@ -3795,11 +3795,11 @@ paths: | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/v2.3/reference/internals/system-buckets/) | `read-orgs` | + | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - - [Manage buckets](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -3908,10 +3908,10 @@ paths: - Buckets summary: Create a bucket description: | - Creates a [bucket](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket) + Creates a [bucket](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket) and returns the bucket resource. The default data - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period) + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS @@ -3930,8 +3930,8 @@ paths: #### Related Guides - - [Create a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/bucket/create) + - [Create a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/bucket/create) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -4137,7 +4137,7 @@ paths: #### Related Guides - - [Update a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/update-bucket/) + - [Update a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/update-bucket/) requestBody: description: The bucket update to apply. required: true @@ -4283,7 +4283,7 @@ paths: #### Related Guides - - [Delete a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4369,7 +4369,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4433,7 +4433,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4559,18 +4559,18 @@ paths: description: | Lists all users for a bucket. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4629,18 +4629,18 @@ paths: description: | Add a user to a bucket and return the new user information. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4720,8 +4720,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4762,7 +4762,7 @@ paths: - Buckets summary: List all owners of a bucket description: | - Lists all [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Lists all [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) of a bucket. Bucket owners have permission to delete buckets and remove user and member @@ -4791,7 +4791,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4842,7 +4842,7 @@ paths: - Buckets summary: Add an owner to a bucket description: | - Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. @@ -4871,7 +4871,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4973,7 +4973,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5015,7 +5015,7 @@ paths: - Security and access endpoints summary: List organizations description: | - Lists [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization/). + Lists [organizations](https://docs.influxdata.com/influxdb/latest/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`. @@ -5026,7 +5026,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -5097,7 +5097,7 @@ paths: - Organizations summary: Create an organization description: | - Creates an [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Creates an [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud @@ -5106,7 +5106,7 @@ paths: #### Related guides - - [Manage organizations](https://docs.influxdata.com/influxdb/v2.3/organizations) + - [Manage organizations](https://docs.influxdata.com/influxdb/latest/organizations) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -5187,7 +5187,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5256,7 +5256,7 @@ paths: #### Related Guides - - [Update an organization](https://docs.influxdata.com/influxdb/v2.3/organizations/update-org/) + - [Update an organization](https://docs.influxdata.com/influxdb/latest/organizations/update-org/) requestBody: description: The organization update to apply. required: true @@ -5324,7 +5324,7 @@ paths: #### Related guides - - [Delete organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/delete-orgs/) + - [Delete organizations](https://docs.influxdata.com/influxdb/latest/organizations/delete-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5438,10 +5438,10 @@ paths: description: | Lists all users that belong to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5463,8 +5463,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5536,10 +5536,10 @@ paths: description: | Add a user to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5559,8 +5559,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5660,7 +5660,7 @@ paths: #### Related guides - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5843,7 +5843,7 @@ paths: - Security and access endpoints summary: Remove an owner from an organization description: | - Removes an [owner](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) from + Removes an [owner](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member @@ -5997,7 +5997,7 @@ paths: #### Related guides - - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/). + - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/). parameters: - in: query name: orgID @@ -6006,7 +6006,7 @@ paths: type: string description: | An organization ID. - Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). #### InfluxDB Cloud @@ -6115,8 +6115,8 @@ paths: #### Related guides - - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). + - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/init/). + - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). requestBody: description: The stack to create. required: true @@ -6311,8 +6311,8 @@ paths: summary: Apply or dry-run a template description: | Applies a template to - create or update a [stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) of InfluxDB - [resources](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/export/all/#resources). + create or update a [stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) of InfluxDB + [resources](https://docs.influxdata.com/influxdb/latest/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. @@ -6328,18 +6328,18 @@ paths: #### Custom values for templates - - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. + - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use - [secrets](https://docs.influxdata.com/influxdb/v2.3/security/secrets/). + [secrets](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template). + For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions @@ -6352,8 +6352,8 @@ paths: #### Related guides - - [Use templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/) - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) + - [Use templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) requestBody: required: true description: | @@ -6639,7 +6639,7 @@ paths: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. If you don't pass query parameters, InfluxDB returns all runs for the task @@ -6653,7 +6653,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to list runs for. - in: query name: after @@ -6675,7 +6675,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after the specified time. - in: query name: beforeTime @@ -6683,7 +6683,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before the specified time. responses: '200': @@ -6726,7 +6726,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to run. requestBody: content: @@ -6765,7 +6765,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -6777,7 +6777,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID @@ -6831,7 +6831,7 @@ paths: - Tasks summary: Cancel a running task description: | - Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to cancel a running task. @@ -6847,7 +6847,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to cancel. - in: path name: runID @@ -6898,7 +6898,7 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to retry and then returns the scheduled run. To manually start a _new_ task run, use the @@ -6921,7 +6921,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: @@ -6988,7 +6988,7 @@ paths: - Tasks summary: List logs for a task description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). When a task runs, InfluxDB creates a `run` record in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. @@ -7002,7 +7002,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve logs for.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for.' responses: '200': description: | @@ -7058,7 +7058,7 @@ paths: Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7066,7 +7066,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the run belongs to.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to.' - in: path name: runID schema: @@ -7163,7 +7163,7 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to add a label to a task. Labels are a way to add metadata to InfluxDB resources. @@ -7178,7 +7178,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. requestBody: description: | In the request body, provide an object that specifies the label. @@ -7211,7 +7211,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7221,7 +7221,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: @@ -7260,7 +7260,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](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -7269,7 +7269,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7317,7 +7317,7 @@ paths: - Users summary: Update a password description: | - Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/latest/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: @@ -7355,7 +7355,7 @@ paths: required: true description: | The user session cookie for the - [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) + [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides @@ -7402,7 +7402,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7412,7 +7412,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. responses: '200': description: | @@ -7440,7 +7440,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7450,7 +7450,7 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. Specifies the task for the member. requestBody: description: | @@ -7487,7 +7487,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7501,7 +7501,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the member from.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from.' responses: '204': description: Success. The member is removed. @@ -7588,7 +7588,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. requestBody: description: | In the request body, provide an object that specifies the user. @@ -7651,7 +7651,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7659,7 +7659,7 @@ paths: schema: type: string required: true - description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task).' + description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task).' - in: path name: taskID schema: @@ -7667,7 +7667,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. responses: '204': description: Success. The owner is removed. @@ -8765,6 +8765,384 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: List authorizations + description: | + Lists authorizations. + + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### 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 + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization).' + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token](https://docs.influxdata.com/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. + responses: + '200': + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + post: + operationId: PostAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token). + + 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 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. + + - 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. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to + + #### Related guides + + - [Create a token](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + examples: + AuthorizationPostRequest: + summary: An authorization for a resource type + description: Creates an authorization. + value: + orgID: INFLUX_ORG_ID + description: iot_users read buckets + permissions: + - action: read + resource: + type: buckets + AuthorizationWithResourcePostRequest: + summary: An authorization for a resource + description: Creates an authorization for access to a specific resource. + value: + orgID: INFLUX_ORG_ID + description: iot_users read buckets + permissions: + - action: read + resource: + type: buckets + id: INFLUX_BUCKET_ID + AuthorizationWithUserPostRequest: + summary: An authorization scoped to a user + description: Creates an authorization scoped to a specific user. + value: + orgID: INFLUX_ORG_ID + userID: INFLUX_USER_ID + description: iot_user write to bucket + permissions: + - action: write + resource: + type: buckets + id: INFLUX_BUCKET_ID + responses: + '201': + description: | + Success. The authorization is created. The response body contains the + authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Retrieve an authorization + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + externalDocs: + url: 'https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/' + description: View tokens + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to retrieve. + responses: + '200': + description: Success. The response body contains the authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. + requestBody: + description: 'In the request body, provide the authorization properties to update.' + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to update. + responses: + '200': + description: Success. The response body contains the updated authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Delete an authorization + 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). + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to delete. + responses: + '204': + description: Success. The authorization is deleted. + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' components: parameters: TraceSpan: @@ -8787,7 +9165,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schema: type: integer minimum: 0 @@ -8827,7 +9205,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schemas: LanguageRequest: description: Flux query to be analyzed. @@ -8955,19 +9333,19 @@ components: properties: start: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. type: string format: date-time stop: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. type: string format: date-time predicate: description: | - An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string Node: @@ -9256,7 +9634,7 @@ components: value: type: boolean DateTimeLiteral: - description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp).' + description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp).' type: object properties: type: @@ -9356,7 +9734,7 @@ components: Dialect: description: | Options for tabular data output. - Default output is [annotated CSV](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) with headers. + Default output is [annotated CSV](https://docs.influxdata.com/influxdb/latest/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). @@ -9379,7 +9757,7 @@ components: #### Related guides - - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) for examples and more information. + - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/latest/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). @@ -9400,7 +9778,7 @@ components: dateTimeFormat: description: | The format for timestamps in results. - Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). + Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values @@ -9434,7 +9812,7 @@ components: type: string description: | The organization ID. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that the authorization is scoped to. + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the authorization is scoped to. permissions: type: array minItems: 1 @@ -9453,20 +9831,20 @@ components: description: | The API token. The token value is unique to the authorization. - [API tokens](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) are + [API tokens](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx` CLI commands--after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). userID: readOnly: true type: string - description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' + description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' user: readOnly: true type: string description: | The user name. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If the authorization is _scoped_ to a user, the user; otherwise, the creator of the authorization. org: @@ -9474,7 +9852,7 @@ components: type: string description: | The organization name. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the token is scoped to. links: type: object @@ -9537,7 +9915,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: @@ -9573,7 +9951,7 @@ components: [Retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. type: string default: '0' @@ -9677,7 +10055,7 @@ components: type: array description: | Retention rules to expire or retain data. - The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). #### InfluxDB Cloud @@ -9730,7 +10108,7 @@ components: type: integer format: int64 description: | - The [shard group duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#shard). + The [shard group duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud @@ -9739,11 +10117,11 @@ components: #### InfluxDB OSS - - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/#shard-group-duration). + - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). #### Related guides - - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/) + - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/) required: - everySeconds RetentionRule: @@ -9778,7 +10156,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -9812,7 +10190,7 @@ components: properties: time: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -9933,7 +10311,7 @@ components: The organization owns all resources created by the template. To find your organization, see how to - [view organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). + [view organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). stackID: type: string description: | @@ -9947,8 +10325,8 @@ components: #### Related guides - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [View stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/view/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [View stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/view/) template: type: object description: | @@ -10000,7 +10378,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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + For more examples, see how to [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -10009,7 +10387,7 @@ components: - `spec.associations.name` For more information about including environment references in template fields, see how to - [include user-definable resource names](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). + [include user-definable resource names](https://docs.influxdata.com/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names). additionalProperties: oneOf: - type: string @@ -10058,7 +10436,7 @@ components: #### Related guides - - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template) additionalProperties: type: string remotes: @@ -11030,7 +11408,7 @@ components: - success - canceled scheduledFor: - description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' + description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' type: string format: date-time log: @@ -11057,7 +11435,7 @@ components: example: '2006-01-02T15:04:05.999999999Z07:00' requestedAt: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -11083,7 +11461,7 @@ components: scheduledFor: nullable: true description: | - The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. type: string @@ -11096,17 +11474,17 @@ components: description: A description of the task. type: string TaskEvery: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string format: duration TaskFlux: description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) and the script for the task to run. #### Related guides - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) type: string format: Flux TaskName: @@ -11119,12 +11497,12 @@ components: TaskOrg: description: | An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskOrgID: description: | An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskStatusType: type: string @@ -13511,7 +13889,7 @@ components: type: string latestCompleted: type: string - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' format: date-time readOnly: true lastRunStatus: @@ -13781,7 +14159,7 @@ components: - endpointID properties: latestCompleted: - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true diff --git a/contracts/legacy.yml b/contracts/legacy.yml index 36c031482..591ceb189 100644 --- a/contracts/legacy.yml +++ b/contracts/legacy.yml @@ -520,18 +520,18 @@ components: properties: orgID: type: string - 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. userID: type: string - 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. token: type: string - description: A name that you provide for the authorization. + description: The name that you provide for the authorization. permissions: type: array minItems: 1 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' @@ -653,7 +653,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: diff --git a/contracts/oss-diff.yml b/contracts/oss-diff.yml index 1f634a0b0..81882661b 100644 --- a/contracts/oss-diff.yml +++ b/contracts/oss-diff.yml @@ -1341,332 +1341,6 @@ paths: default: description: Unexpected error $ref: '#/paths/~1config/get/responses/401' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - - Security and access endpoints - summary: List authorizations - description: | - Lists authorizations. - - 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 OSS returns - [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - - #### Required permissions - - - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - - #### Related guides - - - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: 'An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).' - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - type: object - properties: - links: - readOnly: true - $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' - authorizations: - type: array - items: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1config/get/responses/401' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token). - - 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 - - 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_DOCS_URL %}}/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. - - We recommend creating a generic user to create and manage tokens for writing data. - - #### Related guides - - - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - required: - - orgID - - permissions - allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' - - type: object - properties: - orgID: - type: string - description: | - An organization ID. - Specifies the organization that owns the authorization. - userID: - type: string - description: | - A user ID. - Specifies the user that the authorization is scoped to. - - When a user authenticates with username and password, - InfluxDB generates a _user session_ with all the permissions - specified by all the user's authorizations. - permissions: - type: array - minItems: 1 - description: | - A list of permissions for an authorization. - In the list, provide at least one `permission` object. - - In a `permission`, the `resource.type` property grants access to all - resources of the specified type. - To grant access to only a specific resource, specify the - `resource.id` property. - items: - required: - - action - - resource - properties: - action: - type: string - enum: - - read - - write - resource: - type: object - required: - - type - properties: - type: - type: string - enum: - - authorizations - - buckets - - dashboards - - orgs - - tasks - - telegrafs - - users - - variables - - secrets - - labels - - views - - documents - - notificationRules - - notificationEndpoints - - checks - - dbrp - - annotations - - sources - - scrapers - - notebooks - - remotes - - replications - - instance - - flows - - functions - - subscriptions - description: | - A resource type. - Identifies the API resource's type (or _kind_). - id: - type: string - description: | - A resource ID. - Identifies a specific resource. - name: - type: string - description: | - The name of the resource. - _Note: not all resource types have a `name` property_. - orgID: - type: string - description: | - An organization ID. - Identifies the organization that owns the resource. - org: - type: string - description: | - An organization name. - The organization that owns the resource. - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - '400': - description: Invalid request - $ref: '#/paths/~1config/get/responses/401' - '401': - $ref: '#/paths/~1tasks/get/responses/401' - '500': - $ref: '#/paths/~1users/get/responses/500' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - - Security and access endpoints - summary: Retrieve an authorization - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update an authorization to be active or inactive - requestBody: - description: Authorization to update - required: true - content: - application/json: - schema: - properties: - status: - description: 'Status of the token. If `inactive`, requests using the token will be rejected.' - default: active - type: string - enum: - - active - - inactive - description: - type: string - description: A description of the token. - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to update. - responses: - '200': - description: The active or inactive authorization - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse/properties/auth' - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/paths/~1ready/get/parameters/0' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/paths/~1config/get/responses/401' /variables: get: operationId: GetVariables @@ -5772,7 +5446,17 @@ components: - orgID - permissions allOf: - - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' + - properties: + status: + description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + default: active + type: string + enum: + - active + - inactive + description: + type: string + description: A description of the token. - type: object properties: createdAt: @@ -5795,7 +5479,72 @@ components: The list of permissions. An authorization must have at least one permission. items: - $ref: '#/paths/~1authorizations/post/requestBody/content/application~1json/schema/allOf/1/properties/permissions/items' + required: + - action + - resource + properties: + action: + type: string + enum: + - read + - write + resource: + type: object + required: + - type + properties: + type: + type: string + enum: + - authorizations + - buckets + - dashboards + - orgs + - tasks + - telegrafs + - users + - variables + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + - annotations + - sources + - scrapers + - notebooks + - remotes + - replications + - instance + - flows + - functions + - subscriptions + description: | + A resource type. + Identifies the API resource's type (or _kind_). + id: + type: string + description: | + A resource ID. + Identifies a specific resource. + name: + type: string + description: | + The name of the resource. + _Note: not all resource types have a `name` property_. + orgID: + type: string + description: | + An organization ID. + Identifies the organization that owns the resource. + org: + type: string + description: | + An organization name. + The organization that owns the resource. id: readOnly: true type: string diff --git a/contracts/oss.json b/contracts/oss.json index 7810f447b..cc6ae2444 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -17,7 +17,7 @@ "tags": [ { "name": "Authorizations", - "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- InfluxDB allows access to the API token value immediately after the authorization is created.\n- You can’t change access (read/write) permissions for an API token after it’s created.\n- Tokens stop working when the user who created the token is deleted.\n\nAPI tokens are visible to the user who created the authorization and to any\nuser with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_.\nIn InfluxDB OSS, even if an API token has `read-authorizations` permission, the\ntoken can't be used to view its authorization details.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n#### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" + "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" }, { "name": "Buckets", @@ -41,15 +41,15 @@ }, { "name": "Tasks", - "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n#### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in a `task` object:\n\n\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n" + "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in a `task` object:\n\n\n\n### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n" }, { "name": "Templates", - "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for\neverything from dashboards and Telegraf to notifications and alerts.\nUse InfluxDB templates to quickly configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration with the\nInfluxData community.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n#### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" + "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for\neverything from dashboards and Telegraf to notifications and alerts.\nUse InfluxDB templates to quickly configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration with the\nInfluxData community.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" }, { "name": "Users", - "description": "Manage users for your organization.\nUsers are those with access to InfluxDB.\nTo grant a user permission to access data, add them as a member of an\norganization and provide them with an API token.\n\n#### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/)\n- [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)\n" + "description": "Manage users for your organization.\nUsers are those with access to InfluxDB.\nTo grant a user permission to access data, add them as a member of an\norganization and provide them with an API token.\n\n### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/)\n- [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)\n" }, { "name": "Write", @@ -83,7 +83,7 @@ { "name": "Pagination", "x-traitTag": true, - "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n| Query parameter | Value type | Description |\n|:------------------------ |:--------------------- |:-------------------------------------------|\n| `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n| `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n#### Limitations\n\n- For specific endpoint parameters and examples, see the endpoint definition.\n- If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" + "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n| Query parameter | Value type | Description |\n|:------------------------ |:--------------------- |:-------------------------------------------|\n| `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n| `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n### Limitations\n\n- For specific endpoint parameters and examples, see the endpoint definition.\n- If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" }, { "name": "Response codes", @@ -11208,6 +11208,370 @@ } } }, + "/authorizations": { + "get": { + "operationId": "GetAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "List authorizations", + "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\nTo retrieve an authorization, the request must use an API token that has the\nfollowing permissions:\n\n- `read-authorizations`\n- `read-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "query", + "name": "userID", + "schema": { + "type": "string" + }, + "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "user", + "schema": { + "type": "string" + }, + "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "orgID", + "schema": { + "type": "string" + }, + "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." + }, + { + "in": "query", + "name": "org", + "schema": { + "type": "string" + }, + "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + }, + { + "in": "query", + "name": "token", + "schema": { + "type": "string" + }, + "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nSpecifies an authorization by its `token` property value\nand returns the authorization.\n\n#### InfluxDB OSS\n\n- Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,\n applies other parameters, and then returns the result.\n\n#### Limitations\n\n- The parameter is non-repeatable. If you specify more than one,\n only the first one is used. If a resource with the specified\n property value doesn't exist, then the response body contains an empty list.\n" + } + ], + "responses": { + "200": { + "description": "Success. The response body contains a list of authorizations.\n\nIf the response body is missing authorizations that you expect, check that the API\ntoken used in the request has `read-user` permission for the users (`userID` property value)\nin those authorizations.\n\n#### InfluxDB OSS\n\n- **Warning**: The response body contains authorizations with their\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in clear text.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorizations" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "post": { + "operationId": "PostAuthorizations", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Create an authorization", + "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe API token is the authorization's `token` property value.\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n - InfluxDB allows access to the API token value immediately after the authorization is created.\n - You can’t change access (read/write) permissions for an API token after it’s created.\n - Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n - Create a generic user to create and manage tokens for writing data.\n - Store your tokens in a secure password vault for future access.\n\n#### Required permissions\n\n- `write-authorizations`\n- `write-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + } + ], + "requestBody": { + "description": "The authorization to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationPostRequest" + }, + "examples": { + "AuthorizationPostRequest": { + "$ref": "#/components/examples/AuthorizationPostRequest" + }, + "AuthorizationWithResourcePostRequest": { + "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" + }, + "AuthorizationWithUserPostRequest": { + "$ref": "#/components/examples/AuthorizationWithUserPostRequest" + } + } + } + } + }, + "responses": { + "201": { + "description": "Success. The authorization is created. The response body contains the\nauthorization.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, + "/authorizations/{authID}": { + "get": { + "operationId": "GetAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Retrieve an authorization", + "description": "Retrieves an authorization.\n\nUse this endpoint to retrieve information about an API token, including\nthe token's permissions and the user that the token is scoped to.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "externalDocs": { + "url": "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/", + "description": "View tokens" + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to retrieve." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "patch": { + "operationId": "PatchAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Update an API token to be active or inactive", + "description": "Updates an authorization.\n\nUse this endpoint to set an API token's status to be _active_ or _inactive_.\nInfluxDB rejects requests that use inactive API tokens.\n", + "requestBody": { + "description": "In the request body, provide the authorization properties to update.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationUpdateRequest" + } + } + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to update." + } + ], + "responses": { + "200": { + "description": "Success. The response body contains the updated authorization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Authorization" + } + } + } + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + }, + "delete": { + "operationId": "DeleteAuthorizationsID", + "tags": [ + "Authorizations", + "API tokens", + "Security and access endpoints" + ], + "summary": "Delete an authorization", + "description": "Deletes an authorization.\n\nUse the endpoint to delete an API token.\n\nIf you want to disable an API token instead of delete it,\n[update the authorization's status to `inactive`](#operation/PatchAuthorizationsID).\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "authID", + "schema": { + "type": "string" + }, + "required": true, + "description": "An authorization ID. Specifies the authorization to delete." + } + ], + "responses": { + "204": { + "description": "Success. The authorization is deleted." + }, + "400": { + "description": "Bad request.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The specified resource ID is invalid.\n", + "value": { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "description": "Not found.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "notFound": { + "summary": "The requested authorization doesn't exist.\n", + "value": { + "code": "not found", + "message": "authorization not found" + } + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, "/debug/pprof/all": { "get": { "operationId": "GetDebugPprofAllProfiles", @@ -12468,259 +12832,6 @@ } } }, - "/authorizations": { - "get": { - "operationId": "GetAuthorizations", - "tags": [ - "Authorizations", - "Security and access endpoints" - ], - "summary": "List authorizations", - "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Required permissions\n\n- An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "query", - "name": "userID", - "schema": { - "type": "string" - }, - "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "user", - "schema": { - "type": "string" - }, - "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "orgID", - "schema": { - "type": "string" - }, - "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." - }, - { - "in": "query", - "name": "org", - "schema": { - "type": "string" - }, - "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" - } - ], - "responses": { - "200": { - "description": "Success. The response body contains a list of authorizations.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorizations" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "post": { - "operationId": "PostAuthorizations", - "tags": [ - "Authorizations" - ], - "summary": "Create an authorization", - "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe response contains the new authorization with the generated API token.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any\n user with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_.\n- You can't update an authorization's permissions.\n- Even if an API token has `read-authorizations` permission, the\n token can't be used to view its authorization details.\n- A token stops working when the user who created the authorization is deleted.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - } - ], - "requestBody": { - "description": "The authorization to create.", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationPostRequest" - }, - "examples": { - "AuthorizationPostRequest": { - "$ref": "#/components/examples/AuthorizationPostRequest" - }, - "AuthorizationWithResourcePostRequest": { - "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" - }, - "AuthorizationWithUserPostRequest": { - "$ref": "#/components/examples/AuthorizationWithUserPostRequest" - } - } - } - } - }, - "responses": { - "201": { - "description": "Success. The authorization is created. The response body contains the authorization.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/authorizations/{authID}": { - "get": { - "operationId": "GetAuthorizationsID", - "tags": [ - "Authorizations", - "Security and access endpoints" - ], - "summary": "Retrieve an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The ID of the authorization to get." - } - ], - "responses": { - "200": { - "description": "Authorization details", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "patch": { - "operationId": "PatchAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Update an authorization to be active or inactive", - "requestBody": { - "description": "Authorization to update", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationUpdateRequest" - } - } - } - }, - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The ID of the authorization to update." - } - ], - "responses": { - "200": { - "description": "The active or inactive authorization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - }, - "delete": { - "operationId": "DeleteAuthorizationsID", - "tags": [ - "Authorizations" - ], - "summary": "Delete an authorization", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "path", - "name": "authID", - "schema": { - "type": "string" - }, - "required": true, - "description": "The ID of the authorization to delete." - } - ], - "responses": { - "204": { - "description": "Authorization deleted" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, "/variables": { "get": { "operationId": "GetVariables", @@ -16677,7 +16788,7 @@ "AuthorizationUpdateRequest": { "properties": { "status": { - "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.", "default": "active", "type": "string", "enum": [ diff --git a/contracts/oss.yml b/contracts/oss.yml index 0b4d47e4a..46bcf6092 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -18,28 +18,14 @@ 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](https://docs.influxdata.com/influxdb/v2.3/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_, the session carries the permissions granted by all the user's authorizations. - For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/). + For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/). To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints @@ -49,21 +35,21 @@ tags: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) - - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) - name: Buckets description: | - Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets - have a [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period), + have a [retention period](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) - name: Debug description: | Generate profiling and trace reports. @@ -84,7 +70,7 @@ tags: Delete data from an InfluxDB bucket. - name: Organizations description: | - Create and manage your [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Create and manage your [organizations](https://docs.influxdata.com/influxdb/latest/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. @@ -95,7 +81,7 @@ tags: Retrieve data, analyze queries, and get query suggestions. - name: Tasks description: | - Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the InfluxDB task engine. Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs. @@ -104,7 +90,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -112,10 +98,10 @@ tags: - #### Related guides + ### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Common data processing tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Common data processing tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) - name: Templates description: | Export and apply InfluxDB **templates**. @@ -136,10 +122,10 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - - [InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/) + - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) - name: Users description: | Manage users for your organization. @@ -147,20 +133,20 @@ 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](https://docs.influxdata.com/influxdb/v2.3/influxdb/latest/users/) - - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/v2.3/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) + - [Manage users](https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/) + - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) - name: Write description: | - Write time series data to [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Write time series data to [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). - name: Authentication description: | Use one of the following schemes to authenticate to the InfluxDB API: @@ -173,10 +159,10 @@ tags: - name: Quick start x-traitTag: true description: | - See the [**API Quick Start**](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/) + See the [**API Quick Start**](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. - [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/v2.3/api-guide/client-libraries/) + [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/latest/api-guide/client-libraries/) are available for popular languages and ready to import into your application. - name: Supported operations x-traitTag: true @@ -206,10 +192,10 @@ tags: | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| - | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | - | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | + | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | + | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | - name: Pagination x-traitTag: true description: | @@ -221,7 +207,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, @@ -293,7 +279,7 @@ paths: summary: Create a user session. description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user), + for a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the @@ -399,7 +385,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -444,7 +430,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) servers: - url: '' tags: @@ -1291,7 +1277,7 @@ paths: description: | Writes data to a bucket. - Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud @@ -1326,12 +1312,12 @@ paths: #### Related guides - - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) requestBody: description: | - In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/). + In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/). To send compressed data, do the following: @@ -1341,7 +1327,7 @@ paths: #### Related guides - - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) + - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) required: true content: text/plain: @@ -1409,7 +1395,7 @@ paths: #### Related guides - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) schema: type: string description: Error content type. @@ -1484,7 +1470,7 @@ paths: #### Related guides - - [How to check for write errors](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [How to check for write errors](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) '400': description: | Bad request. The response body contains detail about the error. @@ -1642,8 +1628,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/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/). x-codeSamples: @@ -1669,8 +1655,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). required: true content: application/json: @@ -2563,7 +2549,7 @@ paths: summary: Generate a query Abstract Syntax Tree (AST) description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#abstract-syntax-tree-ast) + Tree (AST)](https://docs.influxdata.com/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query @@ -3896,7 +3882,7 @@ paths: #### Related guides - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/query-data/execute-queries/influx-api/) + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) parameters: - $ref: '#/components/parameters/TraceSpan' @@ -4027,9 +4013,9 @@ paths: description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#adjustable-service-quotas) + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#global-limits) + [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: @@ -4051,19 +4037,19 @@ paths: - Buckets summary: List buckets description: | - Lists [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Lists [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) associated with the authorization - ([API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token)). + ([API token](https://docs.influxdata.com/influxdb/latest/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`. #### InfluxDB OSS - - If you use an _[operator token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/#operator-token)_ + - If you use an _[operator token](https://docs.influxdata.com/influxdb/latest/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 @@ -4074,11 +4060,11 @@ paths: | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/v2.3/reference/internals/system-buckets/) | `read-orgs` | + | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - - [Manage buckets](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -4187,10 +4173,10 @@ paths: - Buckets summary: Create a bucket description: | - Creates a [bucket](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket) + Creates a [bucket](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket) and returns the bucket resource. The default data - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period) + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS @@ -4209,8 +4195,8 @@ paths: #### Related Guides - - [Create a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/bucket/create) + - [Create a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/bucket/create) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -4416,7 +4402,7 @@ paths: #### Related Guides - - [Update a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/update-bucket/) + - [Update a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/update-bucket/) requestBody: description: The bucket update to apply. required: true @@ -4562,7 +4548,7 @@ paths: #### Related Guides - - [Delete a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4648,7 +4634,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4712,7 +4698,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4838,18 +4824,18 @@ paths: description: | Lists all users for a bucket. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4908,18 +4894,18 @@ paths: description: | Add a user to a bucket and return the new user information. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -4999,8 +4985,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5041,7 +5027,7 @@ paths: - Buckets summary: List all owners of a bucket description: | - Lists all [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Lists all [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) of a bucket. Bucket owners have permission to delete buckets and remove user and member @@ -5070,7 +5056,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5121,7 +5107,7 @@ paths: - Buckets summary: Add an owner to a bucket description: | - Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. @@ -5150,7 +5136,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5252,7 +5238,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5294,7 +5280,7 @@ paths: - Security and access endpoints summary: List organizations description: | - Lists [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization/). + Lists [organizations](https://docs.influxdata.com/influxdb/latest/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`. @@ -5305,7 +5291,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -5376,7 +5362,7 @@ paths: - Organizations summary: Create an organization description: | - Creates an [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Creates an [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud @@ -5385,7 +5371,7 @@ paths: #### Related guides - - [Manage organizations](https://docs.influxdata.com/influxdb/v2.3/organizations) + - [Manage organizations](https://docs.influxdata.com/influxdb/latest/organizations) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -5466,7 +5452,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5535,7 +5521,7 @@ paths: #### Related Guides - - [Update an organization](https://docs.influxdata.com/influxdb/v2.3/organizations/update-org/) + - [Update an organization](https://docs.influxdata.com/influxdb/latest/organizations/update-org/) requestBody: description: The organization update to apply. required: true @@ -5603,7 +5589,7 @@ paths: #### Related guides - - [Delete organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/delete-orgs/) + - [Delete organizations](https://docs.influxdata.com/influxdb/latest/organizations/delete-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5717,10 +5703,10 @@ paths: description: | Lists all users that belong to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5742,8 +5728,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5815,10 +5801,10 @@ paths: description: | Add a user to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -5838,8 +5824,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5939,7 +5925,7 @@ paths: #### Related guides - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6122,7 +6108,7 @@ paths: - Security and access endpoints summary: Remove an owner from an organization description: | - Removes an [owner](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) from + Removes an [owner](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member @@ -6276,7 +6262,7 @@ paths: #### Related guides - - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/). + - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/). parameters: - in: query name: orgID @@ -6285,7 +6271,7 @@ paths: type: string description: | An organization ID. - Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). #### InfluxDB Cloud @@ -6394,8 +6380,8 @@ paths: #### Related guides - - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). + - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/init/). + - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). requestBody: description: The stack to create. required: true @@ -6590,8 +6576,8 @@ paths: summary: Apply or dry-run a template description: | Applies a template to - create or update a [stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) of InfluxDB - [resources](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/export/all/#resources). + create or update a [stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) of InfluxDB + [resources](https://docs.influxdata.com/influxdb/latest/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. @@ -6607,18 +6593,18 @@ paths: #### Custom values for templates - - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. + - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use - [secrets](https://docs.influxdata.com/influxdb/v2.3/security/secrets/). + [secrets](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template). + For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions @@ -6631,8 +6617,8 @@ paths: #### Related guides - - [Use templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/) - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) + - [Use templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) requestBody: required: true description: | @@ -6918,7 +6904,7 @@ paths: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. If you don't pass query parameters, InfluxDB returns all runs for the task @@ -6932,7 +6918,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to list runs for. - in: query name: after @@ -6954,7 +6940,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after the specified time. - in: query name: beforeTime @@ -6962,7 +6948,7 @@ paths: type: string format: date-time description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before the specified time. responses: '200': @@ -7005,7 +6991,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to run. requestBody: content: @@ -7044,7 +7030,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -7056,7 +7042,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID @@ -7110,7 +7096,7 @@ paths: - Tasks summary: Cancel a running task description: | - Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to cancel a running task. @@ -7126,7 +7112,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to cancel. - in: path name: runID @@ -7177,7 +7163,7 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to retry and then returns the scheduled run. To manually start a _new_ task run, use the @@ -7200,7 +7186,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: @@ -7267,7 +7253,7 @@ paths: - Tasks summary: List logs for a task description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). When a task runs, InfluxDB creates a `run` record in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. @@ -7281,7 +7267,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve logs for.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for.' responses: '200': description: | @@ -7337,7 +7323,7 @@ paths: Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7345,7 +7331,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the run belongs to.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to.' - in: path name: runID schema: @@ -7442,7 +7428,7 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to add a label to a task. Labels are a way to add metadata to InfluxDB resources. @@ -7457,7 +7443,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. requestBody: description: | In the request body, provide an object that specifies the label. @@ -7490,7 +7476,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7500,7 +7486,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: @@ -7539,7 +7525,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](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -7548,7 +7534,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7596,7 +7582,7 @@ paths: - Users summary: Update a password description: | - Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/latest/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: @@ -7634,7 +7620,7 @@ paths: required: true description: | The user session cookie for the - [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) + [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides @@ -7681,7 +7667,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7691,7 +7677,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. responses: '200': description: | @@ -7719,7 +7705,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7729,7 +7715,7 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. Specifies the task for the member. requestBody: description: | @@ -7766,7 +7752,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7780,7 +7766,7 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the member from.' + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from.' responses: '204': description: Success. The member is removed. @@ -7867,7 +7853,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. requestBody: description: | In the request body, provide an object that specifies the user. @@ -7930,7 +7916,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7938,7 +7924,7 @@ paths: schema: type: string required: true - description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task).' + description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task).' - in: path name: taskID schema: @@ -7946,7 +7932,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. responses: '204': description: Success. The owner is removed. @@ -9044,6 +9030,357 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: List authorizations + description: | + Lists authorizations. + + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### 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 + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization).' + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token](https://docs.influxdata.com/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. + responses: + '200': + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + post: + operationId: PostAuthorizations + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token). + + 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 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. + + - 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. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to + + #### Related guides + + - [Create a token](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + examples: + AuthorizationPostRequest: + $ref: '#/components/examples/AuthorizationPostRequest' + AuthorizationWithResourcePostRequest: + $ref: '#/components/examples/AuthorizationWithResourcePostRequest' + AuthorizationWithUserPostRequest: + $ref: '#/components/examples/AuthorizationWithUserPostRequest' + responses: + '201': + description: | + Success. The authorization is created. The response body contains the + authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: Invalid request + $ref: '#/components/responses/GeneralServerError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Retrieve an authorization + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) + externalDocs: + url: 'https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/' + description: View tokens + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to retrieve. + responses: + '200': + description: Success. The response body contains the authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. + requestBody: + description: 'In the request body, provide the authorization properties to update.' + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to update. + responses: + '200': + description: Success. The response body contains the updated authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + - API tokens + - Security and access endpoints + summary: Delete an authorization + 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). + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: An authorization ID. Specifies the authorization to delete. + responses: + '204': + description: Success. The authorization is deleted. + '400': + description: | + Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + description: | + Not found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + '500': + $ref: '#/components/responses/InternalServerError' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' /debug/pprof/all: get: operationId: GetDebugPprofAllProfiles @@ -9057,7 +9394,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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration) value. + Include by passing the `cpu` query parameter with a [duration](https://docs.influxdata.com/influxdb/latest/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 @@ -9106,7 +9443,7 @@ paths: - in: query name: cpu description: | - Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration). + Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration). schema: type: string format: duration @@ -9824,9 +10161,9 @@ paths: #### Related guides - - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/v2.3/reference/internals/metrics/). - - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/scrape-prometheus-metrics/). - - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/v2.3/reference/prometheus-metrics/). + - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/latest/reference/internals/metrics/). + - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/scrape-prometheus-metrics/). + - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/latest/reference/prometheus-metrics/). servers: - url: '' parameters: @@ -9894,7 +10231,7 @@ paths: - Users summary: List users description: | - Lists [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Lists [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). Default limit is `20`. To limit which users are returned, pass query parameters in your request. @@ -9922,14 +10259,14 @@ paths: type: string description: | A user name. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). - in: query name: id schema: type: string description: | A user ID. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). responses: '200': description: Success. The response contains a list of `users`. @@ -9974,7 +10311,7 @@ paths: - Users summary: Create a user description: | - Creates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that can access InfluxDB. + Creates a [user](https://docs.influxdata.com/influxdb/latest/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 @@ -10090,11 +10427,11 @@ paths: - Users summary: Retrieve a user description: | - Retrieves a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -10104,7 +10441,7 @@ paths: required: true description: | A user ID. - Retrieves the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). responses: '200': description: Success. The response body contains the user. @@ -10121,7 +10458,7 @@ paths: - Users summary: Update a user description: | - Updates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) and returns the user. + Updates a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) and returns the user. #### Required permissions @@ -10133,7 +10470,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) requestBody: description: 'In the request body, provide the user properties to update.' required: true @@ -10150,7 +10487,7 @@ paths: required: true description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to update. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to update. responses: '200': description: | @@ -10176,7 +10513,7 @@ paths: - Users summary: Delete a user description: | - Deletes a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Deletes a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Required permissions @@ -10188,7 +10525,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -10198,7 +10535,7 @@ paths: required: true description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to delete. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to delete. responses: '204': description: Success. The user is deleted. @@ -10258,216 +10595,6 @@ paths: default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' - /authorizations: - get: - operationId: GetAuthorizations - tags: - - Authorizations - - Security and access endpoints - summary: List authorizations - description: | - Lists authorizations. - - 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 OSS returns - [API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - - #### Required permissions - - - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - - #### Related guides - - - [View tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/view-tokens/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization).' - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). - responses: - '200': - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token). - - 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 - - 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](https://docs.influxdata.com/influxdb/v2.3/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. - - We recommend creating a generic user to create and manage tokens for writing data. - - #### Related guides - - - [Create a token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPostRequest' - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - responses: - '201': - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - '/authorizations/{authID}': - get: - operationId: GetAuthorizationsID - tags: - - Authorizations - - Security and access endpoints - summary: Retrieve an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to get. - responses: - '200': - description: Authorization details - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update an authorization to be active or inactive - requestBody: - description: Authorization to update - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to update. - responses: - '200': - description: The active or inactive authorization - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' - delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: authID - schema: - type: string - required: true - description: The ID of the authorization to delete. - responses: - '204': - description: Authorization deleted - default: - description: Unexpected error - $ref: '#/components/responses/GeneralServerError' /variables: get: operationId: GetVariables @@ -11363,7 +11490,7 @@ paths: description: The shard ID. - in: query name: since - description: 'The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) to include in the snapshot.' + description: 'The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) to include in the snapshot.' schema: type: string format: date-time @@ -11619,7 +11746,7 @@ paths: #### Related guides - - [View your runtime server configuration](https://docs.influxdata.com/influxdb/v2.3/reference/config-options/#view-your-runtime-server-configuration) + - [View your runtime server configuration](https://docs.influxdata.com/influxdb/latest/reference/config-options/#view-your-runtime-server-configuration) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -11973,11 +12100,11 @@ paths: - Dashboards summary: List dashboards description: | - Lists [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Lists [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). #### Related guides - - [Manage dashboards](https://docs.influxdata.com/influxdb/v2.3/visualize-data/dashboards/). + - [Manage dashboards](https://docs.influxdata.com/influxdb/latest/visualize-data/dashboards/). parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' @@ -11985,7 +12112,7 @@ paths: - $ref: '#/components/parameters/Descending' - in: query name: owner - description: 'A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) where the specified user has the `owner` role.' + description: 'A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) where the specified user has the `owner` role.' schema: type: string - in: query @@ -12001,7 +12128,7 @@ paths: name: id description: | A list of dashboard IDs. - Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). If you specify `id` and `owner`, only `id` is used. schema: type: array @@ -12011,16 +12138,16 @@ paths: name: orgID description: | An organization ID. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). schema: type: string - in: query name: org description: | An organization name. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). schema: type: string responses: @@ -12044,21 +12171,21 @@ paths: - Tasks summary: List tasks description: | - Lists [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/process-data/) + - [Process data with InfluxDB tasks](https://docs.influxdata.com/influxdb/latest/process-data/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: name description: | A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified name. Different tasks may have the same name. schema: @@ -12069,29 +12196,29 @@ paths: type: string description: | A task ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) created after the specified task. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) created after the specified task. - in: query name: user schema: type: string description: | A user ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) - owned by the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) + owned by the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). - in: query name: org schema: type: string description: | An organization name. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). - in: query name: orgID schema: type: string description: | An organization ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). required: true - in: query name: status @@ -12102,7 +12229,7 @@ paths: - inactive description: | A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that have the specified status. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified status. - in: query name: limit schema: @@ -12111,7 +12238,7 @@ paths: maximum: 500 default: 100 description: | - The maximum number of [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to return. + The maximum number of [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. @@ -12121,7 +12248,7 @@ paths: name: type description: | A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) in the response. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the response. Default is `system`. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). @@ -12226,16 +12353,16 @@ paths: - Tasks summary: Create a task description: | - Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a script. #### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Create a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/create-task/) - - [Common tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Create a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/create-task/) + - [Common tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: @@ -12301,7 +12428,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -12311,7 +12438,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve. responses: '200': description: Success. The response body contains the task. @@ -12335,7 +12462,7 @@ paths: - Tasks summary: Update a task description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task), + Updates the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. @@ -12343,8 +12470,8 @@ paths: #### Related guides - - [Update a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Update a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) requestBody: description: | In the request body, provide the task properties to update. @@ -12365,7 +12492,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task)to update. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task)to update. responses: '200': description: Success. The response body contains the updated task. @@ -12389,7 +12516,7 @@ paths: - Tasks summary: Delete a task description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Deletes the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. @@ -12405,7 +12532,7 @@ paths: required: true description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete. responses: '204': description: Success. The task and runs are deleted. Scheduled runs are canceled. @@ -12441,7 +12568,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schema: type: integer minimum: 0 @@ -12481,7 +12608,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). schemas: LanguageRequest: description: Flux query to be analyzed. @@ -12609,19 +12736,19 @@ components: properties: start: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. type: string format: date-time stop: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. type: string format: date-time predicate: description: | - An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string Node: @@ -12910,7 +13037,7 @@ components: value: type: boolean DateTimeLiteral: - description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp).' + description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp).' type: object properties: type: @@ -13010,7 +13137,7 @@ components: Dialect: description: | Options for tabular data output. - Default output is [annotated CSV](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) with headers. + Default output is [annotated CSV](https://docs.influxdata.com/influxdb/latest/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). @@ -13033,7 +13160,7 @@ components: #### Related guides - - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) for examples and more information. + - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/latest/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). @@ -13054,7 +13181,7 @@ components: dateTimeFormat: description: | The format for timestamps in results. - Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). + Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values @@ -13088,7 +13215,7 @@ components: type: string description: | The organization ID. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that the authorization is scoped to. + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the authorization is scoped to. permissions: type: array minItems: 1 @@ -13107,20 +13234,20 @@ components: description: | The API token. The token value is unique to the authorization. - [API tokens](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) are + [API tokens](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx` CLI commands--after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). userID: readOnly: true type: string - description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' + description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' user: readOnly: true type: string description: | The user name. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the authorization. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the authorization. If the authorization is _scoped_ to a user, the user; otherwise, the creator of the authorization. org: @@ -13128,7 +13255,7 @@ components: type: string description: | The organization name. - Specifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Specifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that the token is scoped to. links: type: object @@ -13191,7 +13318,7 @@ components: AuthorizationUpdateRequest: properties: status: - 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.' default: active type: string enum: @@ -13227,7 +13354,7 @@ components: [Retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. type: string default: '0' @@ -13331,7 +13458,7 @@ components: type: array description: | Retention rules to expire or retain data. - The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). #### InfluxDB Cloud @@ -13384,7 +13511,7 @@ components: type: integer format: int64 description: | - The [shard group duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#shard). + The [shard group duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud @@ -13393,11 +13520,11 @@ components: #### InfluxDB OSS - - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/#shard-group-duration). + - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). #### Related guides - - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/) + - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/) required: - everySeconds RetentionRule: @@ -13432,7 +13559,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -13466,7 +13593,7 @@ components: properties: time: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -13587,7 +13714,7 @@ components: The organization owns all resources created by the template. To find your organization, see how to - [view organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). + [view organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). stackID: type: string description: | @@ -13601,8 +13728,8 @@ components: #### Related guides - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [View stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/view/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [View stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/view/) template: type: object description: | @@ -13654,7 +13781,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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + For more examples, see how to [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -13663,7 +13790,7 @@ components: - `spec.associations.name` For more information about including environment references in template fields, see how to - [include user-definable resource names](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). + [include user-definable resource names](https://docs.influxdata.com/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names). additionalProperties: oneOf: - type: string @@ -13712,7 +13839,7 @@ components: #### Related guides - - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template) additionalProperties: type: string remotes: @@ -14684,7 +14811,7 @@ components: - success - canceled scheduledFor: - description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' + description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' type: string format: date-time log: @@ -14711,7 +14838,7 @@ components: example: '2006-01-02T15:04:05.999999999Z07:00' requestedAt: readOnly: true - description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' + description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' @@ -14737,7 +14864,7 @@ components: scheduledFor: nullable: true description: | - The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. type: string @@ -14750,17 +14877,17 @@ components: description: A description of the task. type: string TaskEvery: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string format: duration TaskFlux: description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) and the script for the task to run. #### Related guides - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) type: string format: Flux TaskName: @@ -14773,12 +14900,12 @@ components: TaskOrg: description: | An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskOrgID: description: | An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskStatusType: type: string @@ -17165,7 +17292,7 @@ components: type: string latestCompleted: type: string - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' format: date-time readOnly: true lastRunStatus: @@ -17435,7 +17562,7 @@ components: - endpointID properties: latestCompleted: - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true @@ -18622,7 +18749,7 @@ components: ownerID: description: | A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the task. + Identifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the task. To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to @@ -18650,7 +18777,7 @@ components: offset: $ref: '#/components/schemas/TaskOffset' latestCompleted: - description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' + description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true @@ -18897,7 +19024,7 @@ components: Replace the following: - *`INFLUX_URL`*: your InfluxDB URL - - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) ### Related endpoints @@ -18905,8 +19032,8 @@ components: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) BasicAuthentication: type: http scheme: basic @@ -18935,7 +19062,7 @@ components: In the examples, replace the following: - **`USERNAME`**: InfluxDB username - - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) - **`INFLUX_URL`**: your InfluxDB URL #### Encode credentials with cURL diff --git a/contracts/priv/cloud-priv.yml b/contracts/priv/cloud-priv.yml index cd90b87d7..ccc061595 100644 --- a/contracts/priv/cloud-priv.yml +++ b/contracts/priv/cloud-priv.yml @@ -883,7 +883,7 @@ components: allOf: - properties: status: - 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.' default: active type: string enum: diff --git a/contracts/ref/cloud.yml b/contracts/ref/cloud.yml index b855849b4..974c7cfac 100644 --- a/contracts/ref/cloud.yml +++ b/contracts/ref/cloud.yml @@ -387,8 +387,8 @@ 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 @@ -2380,22 +2380,23 @@ 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: @@ -6752,7 +6753,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 @@ -6762,7 +6763,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 @@ -6772,39 +6777,46 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to the specified - [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + - description: An organization ID. Only returns authorizations that belong to + the specified [organization](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). in: query name: org schema: type: string - description: | An API [token](https://docs.influxdata.com/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: @@ -6815,7 +6827,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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6829,6 +6853,8 @@ paths: summary: List authorizations tags: - Authorizations + - API tokens + - Security and access endpoints post: description: | Creates an authorization and returns the authorization with the @@ -6836,20 +6862,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 @@ -6878,7 +6908,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 @@ -6892,12 +6923,21 @@ paths: summary: Create an authorization tags: - 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 @@ -6905,18 +6945,71 @@ 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 + - 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/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 @@ -6928,19 +7021,57 @@ 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 + - 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 @@ -6951,7 +7082,8 @@ 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": @@ -6959,13 +7091,15 @@ 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 + - API tokens + - Security and access endpoints /api/v2/buckets: get: description: | @@ -18429,24 +18563,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_, @@ -18494,7 +18616,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](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -18523,7 +18645,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -18531,7 +18653,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/cloud/process-data/get-started/) - [Common data processing tasks](https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/) @@ -18554,7 +18676,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/) @@ -18569,14 +18691,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](https://docs.influxdata.com/influxdb/cloud/organizations/users/) name: Users @@ -18651,7 +18773,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, diff --git a/contracts/ref/oss.yml b/contracts/ref/oss.yml index 350b92605..b86a92fe3 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -53,7 +53,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). in: query name: after required: false @@ -82,7 +82,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/v2.3/api/#tag/Pagination). + For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination). in: query name: offset required: false @@ -372,8 +372,8 @@ 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 @@ -844,7 +844,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true @@ -1290,7 +1290,7 @@ components: type: object DateTimeLiteral: description: Represents an instant in time with nanosecond precision in [RFC3339Nano - date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp). + date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp). properties: type: $ref: '#/components/schemas/NodeType' @@ -1357,18 +1357,18 @@ components: properties: predicate: description: | - An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string start: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. format: date-time type: string stop: description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. format: date-time type: string @@ -1379,7 +1379,7 @@ components: Dialect: description: | Options for tabular data output. - Default output is [annotated CSV](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) with headers. + Default output is [annotated CSV](https://docs.influxdata.com/influxdb/latest/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). @@ -1391,7 +1391,7 @@ components: #### Related guides - - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) for examples and more information. + - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/latest/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). @@ -1414,7 +1414,7 @@ components: default: RFC3339 description: | The format for timestamps in results. - Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). + Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values @@ -2399,22 +2399,23 @@ 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: @@ -2616,7 +2617,7 @@ components: readOnly: true type: string time: - description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) + description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time @@ -2957,7 +2958,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true @@ -3307,7 +3308,7 @@ components: type: integer shardGroupDurationSeconds: description: | - The [shard group duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#shard). + The [shard group duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud @@ -3316,11 +3317,11 @@ components: #### InfluxDB OSS - - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/#shard-group-duration). + - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). #### Related guides - - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/) + - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/) format: int64 type: integer type: @@ -3451,7 +3452,7 @@ components: [Retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. type: string schemaType: @@ -3984,7 +3985,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -3998,7 +3999,7 @@ components: RetentionRules: description: | Retention rules to expire or retain data. - The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period). #### InfluxDB Cloud @@ -4148,14 +4149,14 @@ components: readOnly: true type: array requestedAt: - description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) + description: The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + description: The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. format: date-time type: string @@ -4182,7 +4183,7 @@ components: properties: scheduledFor: description: | - The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. format: date-time @@ -4919,7 +4920,7 @@ components: readOnly: true type: string latestCompleted: - description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true @@ -4958,7 +4959,7 @@ components: ownerID: description: | A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the task. + Identifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the task. To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to @@ -5003,19 +5004,19 @@ components: description: A description of the task. type: string TaskEvery: - description: The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + description: The interval ([duration literal](https://docs.influxdata.com/influxdb/latest/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 TaskFlux: description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) and the script for the task to run. #### Related guides - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) format: Flux type: string TaskName: @@ -5030,12 +5031,12 @@ components: TaskOrg: description: | An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskOrgID: description: | An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. type: string TaskStatusType: description: | @@ -5350,7 +5351,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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + For more examples, see how to [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -5359,7 +5360,7 @@ components: - `spec.associations.name` For more information about including environment references in template fields, see how to - [include user-definable resource names](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). + [include user-definable resource names](https://docs.influxdata.com/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names). type: object orgID: description: | @@ -5368,7 +5369,7 @@ components: The organization owns all resources created by the template. To find your organization, see how to - [view organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). + [view organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). type: string remotes: description: | @@ -5429,7 +5430,7 @@ components: #### Related guides - - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template) type: object stackID: description: | @@ -5443,8 +5444,8 @@ components: #### Related guides - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [View stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/view/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [View stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/view/) type: string template: description: | @@ -6694,7 +6695,7 @@ components: In the examples, replace the following: - **`USERNAME`**: InfluxDB username - - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - **`PASSWORD`**: InfluxDB [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) - **`INFLUX_URL`**: your InfluxDB URL #### Encode credentials with cURL @@ -6764,7 +6765,7 @@ components: Replace the following: - *`INFLUX_URL`*: your InfluxDB URL - - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) + - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) ### Related endpoints @@ -6772,8 +6773,8 @@ components: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) in: header name: Authorization type: apiKey @@ -6816,57 +6817,91 @@ 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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. + - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. #### Required permissions - - An _[operator token](https://docs.influxdata.com/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 - - [View tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/view-tokens/) + - [View tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/) operationId: GetAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: user schema: type: string - description: An organization ID. Only returns authorizations that belong to - the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: org schema: type: string + - description: | + An API [token](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6880,33 +6915,37 @@ paths: summary: List authorizations tags: - Authorizations + - API tokens - Security and access endpoints post: description: | Creates an authorization and returns the authorization with the - generated API [token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token). + generated API [token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token). 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](https://docs.influxdata.com/influxdb/v2.3/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 the following for managing your tokens: - We recommend creating a generic user to create and manage tokens for writing data. + - 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 - - [Create a token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) + - [Create a token](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) operationId: PostAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' @@ -6931,7 +6970,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 @@ -6945,12 +6985,21 @@ paths: summary: Create an authorization tags: - 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 @@ -6958,18 +7007,71 @@ 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 + - 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/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 @@ -6981,19 +7083,57 @@ 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 + - 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 @@ -7004,7 +7144,8 @@ 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": @@ -7012,13 +7153,15 @@ 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 + - API tokens + - Security and access endpoints /api/v2/backup/kv: get: deprecated: true @@ -7110,7 +7253,7 @@ paths: schema: format: int64 type: integer - - description: The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) + - description: The earliest time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp) to include in the snapshot. examples: RFC3339: @@ -7156,19 +7299,19 @@ paths: /api/v2/buckets: get: description: | - Lists [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Lists [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) associated with the authorization - ([API token](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#token)). + ([API token](https://docs.influxdata.com/influxdb/latest/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`. #### InfluxDB OSS - - If you use an _[operator token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/#operator-token)_ + - If you use an _[operator token](https://docs.influxdata.com/influxdb/latest/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 @@ -7179,11 +7322,11 @@ paths: | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/v2.3/reference/internals/system-buckets/) | `read-orgs` | + | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - - [Manage buckets](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) operationId: GetBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7292,10 +7435,10 @@ paths: --header "Content-Type: application/json" post: description: | - Creates a [bucket](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket) + Creates a [bucket](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket) and returns the bucket resource. The default data - [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period) + [retention period](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS @@ -7314,8 +7457,8 @@ paths: #### Related Guides - - [Create a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/bucket/create) + - [Create a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/bucket/create) operationId: PostBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7452,7 +7595,7 @@ paths: #### Related Guides - - [Delete a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) operationId: DeleteBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7615,7 +7758,7 @@ paths: #### Related Guides - - [Update a bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/update-bucket/) + - [Update a bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/update-bucket/) operationId: PatchBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7754,7 +7897,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) operationId: GetBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7818,7 +7961,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](https://docs.influxdata.com/influxdb/v2.3/visualize-data/labels/) + - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/latest/visualize-data/labels/) operationId: PostBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7944,18 +8087,18 @@ paths: description: | Lists all users for a bucket. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: GetBucketsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8014,18 +8157,18 @@ paths: description: | Add a user to a bucket and return the new user information. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users in + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: PostBucketsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8105,8 +8248,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: DeleteBucketsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8147,7 +8290,7 @@ paths: /api/v2/buckets/{bucketID}/owners: get: description: | - Lists all [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Lists all [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) of a bucket. Bucket owners have permission to delete buckets and remove user and member @@ -8176,7 +8319,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) operationId: GetBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8227,7 +8370,7 @@ paths: - Buckets post: description: | - Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) + Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. @@ -8256,7 +8399,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) operationId: PostBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8358,7 +8501,7 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) operationId: DeleteBucketsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8727,7 +8870,7 @@ paths: #### Related guides - - [View your runtime server configuration](https://docs.influxdata.com/influxdb/v2.3/reference/config-options/#view-your-runtime-server-configuration) + - [View your runtime server configuration](https://docs.influxdata.com/influxdb/latest/reference/config-options/#view-your-runtime-server-configuration) operationId: GetConfig parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8751,18 +8894,18 @@ paths: /api/v2/dashboards: get: description: | - Lists [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Lists [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). #### Related guides - - [Manage dashboards](https://docs.influxdata.com/influxdb/v2.3/visualize-data/dashboards/). + - [Manage dashboards](https://docs.influxdata.com/influxdb/latest/visualize-data/dashboards/). operationId: GetDashboards parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Descending' - - description: A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) + - description: A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) where the specified user has the `owner` role. in: query name: owner @@ -8779,7 +8922,7 @@ paths: type: string - description: | A list of dashboard IDs. - Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard). + Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard). If you specify `id` and `owner`, only `id` is used. in: query name: id @@ -8789,16 +8932,16 @@ paths: type: array - description: | An organization ID. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns [dashboards](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#dashboard) that belong to the specified - [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [dashboards](https://docs.influxdata.com/influxdb/latest/reference/glossary/#dashboard) that belong to the specified + [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: org schema: @@ -9735,7 +9878,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](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration) value. + Include by passing the `cpu` query parameter with a [duration](https://docs.influxdata.com/influxdb/latest/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 @@ -9745,7 +9888,7 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#duration). + Collects and returns CPU profiling data for the specified [duration](https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration). in: query name: cpu schema: @@ -10506,8 +10649,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/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 @@ -10584,8 +10727,8 @@ paths: #### Related guides - - [Delete data](https://docs.influxdata.com/influxdb/v2.3/write-data/delete-data/) - - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](https://docs.influxdata.com/influxdb/latest/write-data/delete-data/) + - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/latest/reference/syntax/delete-predicate/). required: true responses: "204": @@ -10662,7 +10805,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](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -10671,7 +10814,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/v2.3/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10898,7 +11041,7 @@ paths: /api/v2/me/password: put: description: | - Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/latest/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: @@ -10930,7 +11073,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | The user session cookie for the - [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) + [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides @@ -10985,9 +11128,9 @@ paths: #### Related guides - - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/v2.3/reference/internals/metrics/). - - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/scrape-prometheus-metrics/). - - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/v2.3/reference/prometheus-metrics/). + - For the list of metrics categories, see [InfluxDB OSS metrics](https://docs.influxdata.com/influxdb/latest/reference/internals/metrics/). + - Learn how to use InfluxDB to [scrape Prometheus metrics](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/scrape-prometheus-metrics/). + - Learn how InfluxDB [parses the Prometheus exposition format](https://docs.influxdata.com/influxdb/latest/reference/prometheus-metrics/). operationId: GetMetrics parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11653,7 +11796,7 @@ paths: /api/v2/orgs: get: description: | - Lists [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization/). + Lists [organizations](https://docs.influxdata.com/influxdb/latest/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`. @@ -11664,7 +11807,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) operationId: GetOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11736,7 +11879,7 @@ paths: - Security and access endpoints post: description: | - Creates an [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) + Creates an [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud @@ -11745,7 +11888,7 @@ paths: #### Related guides - - [Manage organizations](https://docs.influxdata.com/influxdb/v2.3/organizations) + - [Manage organizations](https://docs.influxdata.com/influxdb/latest/organizations) operationId: PostOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11843,7 +11986,7 @@ paths: #### Related guides - - [Delete organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/delete-orgs/) + - [Delete organizations](https://docs.influxdata.com/influxdb/latest/organizations/delete-orgs/) operationId: DeleteOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11902,7 +12045,7 @@ paths: #### Related guides - - [View organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/) operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11972,7 +12115,7 @@ paths: #### Related Guides - - [Update an organization](https://docs.influxdata.com/influxdb/v2.3/organizations/update-org/) + - [Update an organization](https://docs.influxdata.com/influxdb/latest/organizations/update-org/) operationId: PatchOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12019,10 +12162,10 @@ paths: description: | Lists all users that belong to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -12044,8 +12187,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: GetOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12118,10 +12261,10 @@ paths: description: | Add a user to an organization. - InfluxDB [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) have + InfluxDB [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) have permission to access InfluxDB. - [Members](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#member) are users + [Members](https://docs.influxdata.com/influxdb/latest/reference/glossary/#member) are users within the organization. #### InfluxDB Cloud @@ -12141,8 +12284,8 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/users/) - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/users/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: PostOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12241,7 +12384,7 @@ paths: #### Related guides - - [Manage members](https://docs.influxdata.com/influxdb/v2.3/organizations/members/) + - [Manage members](https://docs.influxdata.com/influxdb/latest/organizations/members/) operationId: DeleteOrgsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12424,7 +12567,7 @@ paths: /api/v2/orgs/{orgID}/owners/{userID}: delete: description: | - Removes an [owner](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#owner) from + Removes an [owner](https://docs.influxdata.com/influxdb/latest/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member @@ -12615,7 +12758,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) operationId: GetPing responses: "204": @@ -12660,7 +12803,7 @@ paths: #### Related guides - - [Influx ping](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/ping/) + - [Influx ping](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/) operationId: HeadPing responses: "204": @@ -12704,7 +12847,7 @@ paths: #### Related guides - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/query-data/execute-queries/influx-api/) + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) operationId: PostQuery parameters: @@ -12828,9 +12971,9 @@ paths: description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#adjustable-service-quotas) + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/v2.3/account-management/limits/#global-limits) + [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: @@ -13017,7 +13160,7 @@ paths: post: description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#abstract-syntax-tree-ast) + Tree (AST)](https://docs.influxdata.com/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query @@ -15211,7 +15354,7 @@ paths: post: description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user), + for a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the @@ -15539,12 +15682,12 @@ paths: #### Related guides - - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/). + - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/). operationId: ListStacks parameters: - description: | An organization ID. - Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). #### InfluxDB Cloud @@ -15659,8 +15802,8 @@ paths: #### Related guides - - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). + - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/init/). + - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). operationId: CreateStack requestBody: content: @@ -15854,20 +15997,20 @@ paths: /api/v2/tasks: get: description: | - Lists [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/process-data/) + - [Process data with InfluxDB tasks](https://docs.influxdata.com/influxdb/latest/process-data/) operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified name. Different tasks may have the same name. in: query @@ -15876,29 +16019,29 @@ paths: type: string - description: | A task ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) created after the specified task. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) created after the specified task. in: query name: after schema: type: string - description: | A user ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) - owned by the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) + owned by the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: user schema: type: string - description: | An organization name. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: org schema: type: string - description: | An organization ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). in: query name: orgID required: true @@ -15906,7 +16049,7 @@ paths: type: string - description: | A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that have the specified status. + Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified status. in: query name: status schema: @@ -15915,7 +16058,7 @@ paths: - inactive type: string - description: | - The maximum number of [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to return. + The maximum number of [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. @@ -15930,7 +16073,7 @@ paths: type: integer - description: | A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) in the response. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the response. Default is `system`. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). @@ -16036,16 +16179,16 @@ paths: --header 'Authorization: Token INFLUX_API_TOKEN' post: description: | - Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a script. #### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Create a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/create-task/) - - [Common tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Create a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/create-task/) + - [Common tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) operationId: PostTasks parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16113,7 +16256,7 @@ paths: /api/v2/tasks/{taskID}: delete: description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Deletes the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. @@ -16125,7 +16268,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete. in: path name: taskID required: true @@ -16150,13 +16293,13 @@ paths: - Tasks get: description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve. in: path name: taskID required: true @@ -16185,7 +16328,7 @@ paths: - Tasks patch: description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task), + Updates the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. @@ -16193,14 +16336,14 @@ paths: #### Related guides - - [Update a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + - [Update a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task)to update. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task)to update. in: path name: taskID required: true @@ -16280,7 +16423,7 @@ paths: - Tasks post: description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to add a label to a task. Labels are a way to add metadata to InfluxDB resources. @@ -16291,7 +16434,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. in: path name: taskID required: true @@ -16328,13 +16471,13 @@ paths: /api/v2/tasks/{taskID}/labels/{labelID}: delete: description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. in: path name: taskID required: true @@ -16367,7 +16510,7 @@ paths: /api/v2/tasks/{taskID}/logs: get: description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). When a task runs, InfluxDB creates a `run` record in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. @@ -16377,7 +16520,7 @@ paths: operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for. in: path name: taskID @@ -16446,13 +16589,13 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. in: path name: taskID required: true @@ -16484,13 +16627,13 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. Specifies the task for the member. in: path name: taskID @@ -16531,7 +16674,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16541,7 +16684,7 @@ paths: required: true schema: type: string - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from. in: path name: taskID @@ -16629,7 +16772,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. in: path name: taskID required: true @@ -16696,11 +16839,11 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). in: path name: userID required: true @@ -16708,7 +16851,7 @@ paths: type: string - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. in: path name: taskID required: true @@ -16729,7 +16872,7 @@ paths: /api/v2/tasks/{taskID}/runs: get: description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. If you don't pass query parameters, InfluxDB returns all runs for the task @@ -16739,7 +16882,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to list runs for. in: path name: taskID @@ -16762,7 +16905,7 @@ paths: minimum: 1 type: integer - description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after the specified time. in: query name: afterTime @@ -16770,7 +16913,7 @@ paths: format: date-time type: string - description: | - A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). + A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before the specified time. in: query name: beforeTime @@ -16812,7 +16955,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to run. in: path name: taskID @@ -16856,7 +16999,7 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}: delete: description: | - Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to cancel a running task. @@ -16868,7 +17011,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to to cancel. in: path name: taskID @@ -16922,7 +17065,7 @@ paths: - Tasks get: description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. operationId: GetTasksIDRunsID @@ -16930,7 +17073,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. in: path name: taskID @@ -16995,11 +17138,11 @@ paths: Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to. in: path name: taskID @@ -17069,7 +17212,7 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}/retry: post: description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to retry and then returns the scheduled run. To manually start a _new_ task run, use the @@ -17083,7 +17226,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. + Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. in: path name: taskID required: true @@ -17617,8 +17760,8 @@ paths: post: description: | Applies a template to - create or update a [stack](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) of InfluxDB - [resources](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/export/all/#resources). + create or update a [stack](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) of InfluxDB + [resources](https://docs.influxdata.com/influxdb/latest/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. @@ -17634,18 +17777,18 @@ paths: #### Custom values for templates - - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. + - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). + [define environment references](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use - [secrets](https://docs.influxdata.com/influxdb/v2.3/security/secrets/). + [secrets](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template). + For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions @@ -17658,8 +17801,8 @@ paths: #### Related guides - - [Use templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/) - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) + - [Use templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/use/) + - [Stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) operationId: ApplyTemplate requestBody: content: @@ -17948,7 +18091,7 @@ paths: /api/v2/users: get: description: | - Lists [users](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Lists [users](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). Default limit is `20`. To limit which users are returned, pass query parameters in your request. @@ -17973,14 +18116,14 @@ paths: - $ref: '#/components/parameters/After' - description: | A user name. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: name schema: type: string - description: | A user ID. - Only lists the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Only lists the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: query name: id schema: @@ -18029,7 +18172,7 @@ paths: - Users post: description: | - Creates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that can access InfluxDB. + Creates a [user](https://docs.influxdata.com/influxdb/latest/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 @@ -18144,7 +18287,7 @@ paths: /api/v2/users/{userID}: delete: description: | - Deletes a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Deletes a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Required permissions @@ -18156,13 +18299,13 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) operationId: DeleteUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to delete. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to delete. in: path name: userID required: true @@ -18191,17 +18334,17 @@ paths: - Users get: description: | - Retrieves a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) operationId: GetUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Retrieves the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). + Retrieves the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). in: path name: userID required: true @@ -18223,7 +18366,7 @@ paths: - Users patch: description: | - Updates a [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) and returns the user. + Updates a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) and returns the user. #### Required permissions @@ -18235,13 +18378,13 @@ paths: #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/v2.3/organizations/users/) + - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) operationId: PatchUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Specifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) to update. + Specifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) to update. in: path name: userID required: true @@ -18691,7 +18834,7 @@ paths: description: | Writes data to a bucket. - Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/) format to InfluxDB. + Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud @@ -18726,9 +18869,9 @@ paths: #### Related guides - - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.3/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) operationId: PostWrite parameters: - $ref: '#/components/parameters/TraceSpan' @@ -18784,7 +18927,7 @@ paths: #### Related guides - - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) in: header name: Accept schema: @@ -18857,7 +19000,7 @@ paths: format: byte type: string description: | - In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/line-protocol/). + In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/latest/reference/syntax/line-protocol/). To send compressed data, do the following: @@ -18867,7 +19010,7 @@ paths: #### Related guides - - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/v2.3/write-data/best-practices/optimize-writes/) + - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/latest/write-data/best-practices/optimize-writes/) required: true responses: "204": @@ -18885,7 +19028,7 @@ paths: #### Related guides - - [How to check for write errors](https://docs.influxdata.com/influxdb/v2.3/write-data/troubleshoot/) + - [How to check for write errors](https://docs.influxdata.com/influxdb/latest/write-data/troubleshoot/) "400": content: application/json: @@ -19527,28 +19670,14 @@ 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](https://docs.influxdata.com/influxdb/v2.3/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_, the session carries the permissions granted by all the user's authorizations. - For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/). + For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/). To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints @@ -19558,21 +19687,21 @@ tags: ### Related guides - - [Authorize API requests](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/#authentication) - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.3/security/tokens/) - - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) + - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) + - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) name: Authorizations - description: | - Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets - have a [retention period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period), + have a [retention period](https://docs.influxdata.com/influxdb/latest/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](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](https://docs.influxdata.com/influxdb/latest/organizations/buckets/) name: Buckets - description: | Generate profiling and trace reports. @@ -19593,7 +19722,7 @@ tags: Delete data from an InfluxDB bucket. name: Delete - description: | - Create and manage your [organizations](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + Create and manage your [organizations](https://docs.influxdata.com/influxdb/latest/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. @@ -19604,7 +19733,7 @@ tags: Retrieve data, analyze queries, and get query suggestions. name: Query - description: | - Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the InfluxDB task engine. Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs. @@ -19613,7 +19742,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -19621,10 +19750,10 @@ tags: - #### Related guides + ### Related guides - - [Get started with tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/get-started/) - - [Common data processing tasks](https://docs.influxdata.com/influxdb/v2.3/process-data/common-tasks/) + - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) + - [Common data processing tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) name: Tasks - description: | Export and apply InfluxDB **templates**. @@ -19645,10 +19774,10 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - - [InfluxDB stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - [InfluxDB templates](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/) + - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) + - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) name: Templates - description: | Manage users for your organization. @@ -19656,20 +19785,20 @@ 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](https://docs.influxdata.com/influxdb/v2.3/influxdb/latest/users/) - - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/v2.3/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) + - [Manage users](https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/) + - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) name: Users - description: | - Write time series data to [buckets](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#bucket). + Write time series data to [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). name: Write - description: | Use one of the following schemes to authenticate to the InfluxDB API: @@ -19681,10 +19810,10 @@ tags: name: Authentication x-traitTag: true - description: | - See the [**API Quick Start**](https://docs.influxdata.com/influxdb/v2.3/api-guide/api_intro/) + See the [**API Quick Start**](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. - [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/v2.3/api-guide/client-libraries/) + [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/latest/api-guide/client-libraries/) are available for popular languages and ready to import into your application. name: Quick start x-traitTag: true @@ -19724,10 +19853,10 @@ tags: | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| - | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/v2.3/organizations/buckets/view-buckets/). | - | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | - | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). | + | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). | + | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | + | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). | name: Common parameters x-traitTag: true - description: | @@ -19739,7 +19868,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, diff --git a/src/cloud.yml b/src/cloud.yml index 329549154..ee3d12d30 100644 --- a/src/cloud.yml +++ b/src/cloud.yml @@ -21,10 +21,6 @@ paths: $ref: './cloud/paths/setup.yml' /setup/user: $ref: './cloud/paths/setup_user.yml' - /authorizations: - $ref: './cloud/paths/authorizations.yml' - /authorizations/{authID}: - $ref: './cloud/paths/authorizations_authID.yml' /variables: $ref: './cloud/paths/variables.yml' '/variables/{variableID}': diff --git a/src/cloud/paths/authorizations.yml b/src/cloud/paths/authorizations.yml deleted file mode 100644 index eb20d6ac9..000000000 --- a/src/cloud/paths/authorizations.yml +++ /dev/null @@ -1,145 +0,0 @@ -get: - operationId: GetAuthorizations - tags: - - Authorizations - summary: List authorizations - description: | - 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. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - - `read-authorizations` - - #### Related guides - - - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: query - name: userID - schema: - type: string - description: | - A user ID. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: user - schema: - type: string - description: | - A user name. - Only returns authorizations scoped to the specified - [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). - - in: query - name: orgID - schema: - type: string - description: | - An organization ID. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: org - schema: - type: string - description: | - An organization name. - Only returns authorizations that belong to the specified - [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value. - Returns the authorization for the specified token. - responses: - "200": - description: Success. The response body contains a list of authorizations. - content: - application/json: - schema: - $ref: "../../common/schemas/Authorizations.yml" - "400": - description: Invalid request - $ref: '../../common/responses/ServerError.yml' - "401": - $ref: "../../common/responses/AuthorizationError.yml" - "500": - $ref: "../../common/responses/InternalServerError.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' -post: - operationId: PostAuthorizations - tags: - - Authorizations - summary: Create an authorization - description: | - Creates an authorization and returns the authorization with the - generated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token). - - 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 - - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud 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. - - 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. - - #### Related guides - - - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - requestBody: - description: The authorization to create. - required: true - content: - application/json: - schema: - $ref: "../../common/schemas/AuthorizationPostRequest.yml" - examples: - AuthorizationPostRequest: - $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationPostRequest" - AuthorizationWithResourcePostRequest: - $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithResourcePostRequest" - AuthorizationWithUserPostRequest: - $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithUserPostRequest" - responses: - "201": - description: | - Success. The authorization is created. The response body contains the authorization. - content: - application/json: - schema: - $ref: "../../common/schemas/Authorization.yml" - "400": - description: Invalid request - $ref: '../../common/responses/ServerError.yml' - "401": - $ref: "../../common/responses/AuthorizationError.yml" - "500": - $ref: "../../common/responses/InternalServerError.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' diff --git a/src/cloud/paths/authorizations_authID.yml b/src/cloud/paths/authorizations_authID.yml deleted file mode 100644 index c85317bfb..000000000 --- a/src/cloud/paths/authorizations_authID.yml +++ /dev/null @@ -1,73 +0,0 @@ -get: - operationId: GetAuthorizationsID - tags: - - Authorizations - summary: Retrieve an authorization - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to get. - responses: - "200": - description: Authorization details - content: - application/json: - schema: - $ref: "../../common/schemas/Authorization.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' -patch: - operationId: PatchAuthorizationsID - tags: - - Authorizations - summary: Update authorization status - description: Update an authorization's status to `active` or `inactive`. - requestBody: - description: The updated Authorization object. - required: true - content: - application/json: - schema: - $ref: "../../common/schemas/AuthorizationUpdateRequest.yml" - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to update. - responses: - "200": - description: The updated authorization. - content: - application/json: - schema: - $ref: "../../common/schemas/Authorization.yml" - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' -delete: - operationId: DeleteAuthorizationsID - tags: - - Authorizations - summary: Delete an authorization - parameters: - - $ref: "../../common/parameters/TraceSpan.yml" - - in: path - name: authID - schema: - type: string - required: true - description: The identifier of the authorization to delete. - responses: - "204": - description: Authorization deleted - default: - description: Unexpected error - $ref: '../../common/responses/ServerError.yml' diff --git a/src/cloud/tags.yml b/src/cloud/tags.yml index e37e5b34c..9b09776f6 100644 --- a/src/cloud/tags.yml +++ b/src/cloud/tags.yml @@ -7,24 +7,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_, @@ -72,7 +60,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_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -101,7 +89,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -109,7 +97,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/) - [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/) @@ -132,7 +120,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/) - [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/) @@ -147,14 +135,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_DOCS_URL %}}/organizations/users/) - name: Write @@ -235,7 +223,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, diff --git a/src/common/_paths.yml b/src/common/_paths.yml index 6f21ef6b9..3d9dcfd8d 100644 --- a/src/common/_paths.yml +++ b/src/common/_paths.yml @@ -174,3 +174,7 @@ $ref: "./common/paths/notificationEndpoints_endpointID_labels.yml" "/notificationEndpoints/{endpointID}/labels/{labelID}": $ref: "./common/paths/notificationEndpoints_endpointID_labels_labelID.yml" + /authorizations: + $ref: "./common/paths/authorizations.yml" + /authorizations/{authID}: + $ref: "./common/paths/authorizations_authID.yml" diff --git a/src/common/paths/authorizations.yml b/src/common/paths/authorizations.yml index 53491a4fd..1a8fabea9 100644 --- a/src/common/paths/authorizations.yml +++ b/src/common/paths/authorizations.yml @@ -2,6 +2,7 @@ get: operationId: GetAuthorizations tags: - Authorizations + - API tokens - Security and access endpoints summary: List authorizations description: | @@ -10,16 +11,19 @@ get: 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_DOCS_URL %}}/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. + - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. #### Required permissions - - An _[operator token](https://docs.influxdata.com/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 @@ -54,9 +58,40 @@ get: description: | An organization name. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token]({{% INFLUXDB_DOCS_URL %}}/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. responses: "200": - 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_DOCS_URL %}}/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. content: application/json: schema: @@ -75,6 +110,8 @@ post: operationId: PostAuthorizations tags: - Authorizations + - API tokens + - Security and access endpoints summary: Create an authorization description: | Creates an authorization and returns the authorization with the @@ -82,21 +119,24 @@ post: 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_DOCS_URL %}}/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 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 - We recommend creating a generic user to create and manage tokens for writing data. + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to #### Related guides @@ -120,7 +160,8 @@ post: responses: "201": description: | - Success. The authorization is created. The response body contains the authorization. + Success. The authorization is created. The response body contains the + authorization. content: application/json: schema: diff --git a/src/common/paths/authorizations_authID.yml b/src/common/paths/authorizations_authID.yml index 768e62822..9ddcfc44d 100644 --- a/src/common/paths/authorizations_authID.yml +++ b/src/common/paths/authorizations_authID.yml @@ -2,8 +2,28 @@ get: operationId: GetAuthorizationsID tags: - Authorizations + - API tokens - Security and access endpoints summary: Retrieve an authorization + 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_DOCS_URL %}}/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) + externalDocs: + url: "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/" + description: View tokens parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -11,14 +31,48 @@ get: schema: type: string required: true - description: The ID of the authorization to get. + description: An authorization ID. Specifies the authorization to retrieve. responses: "200": - description: Authorization details + description: Success. The response body contains the authorization. content: application/json: schema: $ref: "../../common/schemas/Authorization.yml" + "400": + description: | + Bad request. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + "401": + $ref: "../responses/AuthorizationError.yml" + "404": + description: | + Not found. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: { + "code": "not found", + "message": "authorization not found" + } + "500": + $ref: "../responses/InternalServerError.yml" default: description: Unexpected error $ref: '../../common/responses/ServerError.yml' @@ -26,9 +80,16 @@ patch: operationId: PatchAuthorizationsID tags: - Authorizations - summary: Update an authorization to be active or inactive + - API tokens + - Security and access endpoints + summary: Update an API token to be 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. requestBody: - description: Authorization to update + description: In the request body, provide the authorization properties to update. required: true content: application/json: @@ -41,10 +102,10 @@ patch: schema: type: string required: true - description: The ID of the authorization to update. + description: An authorization ID. Specifies the authorization to update. responses: "200": - description: The active or inactive authorization + description: Success. The response body contains the updated authorization. content: application/json: schema: @@ -56,7 +117,16 @@ delete: operationId: DeleteAuthorizationsID tags: - Authorizations + - API tokens + - Security and access endpoints summary: Delete an authorization + 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). parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -64,10 +134,44 @@ delete: schema: type: string required: true - description: The ID of the authorization to delete. + description: An authorization ID. Specifies the authorization to delete. responses: "204": - description: Authorization deleted + description: Success. The authorization is deleted. + "400": + description: | + Bad request. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: { + "code": "invalid", + "message": "id must have a length of 16 bytes" + } + "401": + $ref: "../responses/AuthorizationError.yml" + "404": + description: | + Not found. + content: + application/json: + schema: + $ref: "../schemas/Error.yml" + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: { + "code": "not found", + "message": "authorization not found" + } + "500": + $ref: "../responses/InternalServerError.yml" default: description: Unexpected error $ref: '../../common/responses/ServerError.yml' diff --git a/src/common/schemas/AuthorizationUpdateRequest.yml b/src/common/schemas/AuthorizationUpdateRequest.yml index 598a251a4..c07b46ce1 100644 --- a/src/common/schemas/AuthorizationUpdateRequest.yml +++ b/src/common/schemas/AuthorizationUpdateRequest.yml @@ -1,6 +1,6 @@ properties: status: - 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. default: active type: string enum: diff --git a/src/legacy/schemas/LegacyAuthorizationPostRequest.yml b/src/legacy/schemas/LegacyAuthorizationPostRequest.yml index 5b572add1..818c5a012 100644 --- a/src/legacy/schemas/LegacyAuthorizationPostRequest.yml +++ b/src/legacy/schemas/LegacyAuthorizationPostRequest.yml @@ -5,18 +5,18 @@ allOf: properties: orgID: type: string - 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. userID: type: string - 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. token: type: string - description: A name that you provide for the authorization. + description: The name that you provide for the authorization. permissions: type: array minItems: 1 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: "../../common/schemas/Permission.yml" diff --git a/src/oss.yml b/src/oss.yml index f325a28a9..b4596b0d5 100644 --- a/src/oss.yml +++ b/src/oss.yml @@ -45,10 +45,6 @@ paths: $ref: "./common/paths/users_userID.yml" /setup: $ref: "./common/paths/setup.yml" - /authorizations: - $ref: "./common/paths/authorizations.yml" - /authorizations/{authID}: - $ref: "./common/paths/authorizations_authID.yml" /variables: $ref: "./common/paths/variables.yml" "/variables/{variableID}": diff --git a/src/oss/tags.yml b/src/oss/tags.yml index 5879b2864..fe6c356b5 100644 --- a/src/oss/tags.yml +++ b/src/oss/tags.yml @@ -7,23 +7,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_DOCS_URL %}}/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_, @@ -93,7 +79,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -101,7 +87,7 @@ tags: - #### Related guides + ### Related guides - [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/) - [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/) @@ -125,7 +111,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/) - [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/) @@ -136,14 +122,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_DOCS_URL %}}/influxdb/latest/users/) - [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) @@ -225,7 +211,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,