diff --git a/contracts/cloud-diff.yml b/contracts/cloud-diff.yml index 8226ab83f..cb7a317a4 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 @@ -4028,7 +3692,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). required: - everySeconds labels: @@ -4041,7 +3705,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: @@ -4064,7 +3738,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 @@ -4831,7 +4570,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides diff --git a/contracts/cloud.json b/contracts/cloud.json index 5a2257945..d1611b75e 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -16,8 +16,8 @@ ], "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" + "name": "Authorizations (API tokens)", + "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", @@ -6219,7 +6219,7 @@ "Buckets" ], "summary": "List all owners of a bucket", - "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6295,7 +6295,7 @@ "Buckets" ], "summary": "Add an owner to a bucket", - "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6393,7 +6393,7 @@ "Buckets" ], "summary": "Remove an owner from a bucket", - "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6949,7 +6949,7 @@ "Security and access endpoints" ], "summary": "List all members of an organization", - "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7050,7 +7050,7 @@ "Organizations" ], "summary": "Add a member to an organization", - "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7149,7 +7149,7 @@ "Security and access endpoints" ], "summary": "Remove a member from an organization", - "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7207,7 +7207,7 @@ "Security and access endpoints" ], "summary": "List all owners of an organization", - "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", + "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7281,7 +7281,7 @@ "Organizations" ], "summary": "Add an owner to an organization", - "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n", + "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7371,7 +7371,7 @@ "Security and access endpoints" ], "summary": "Remove an owner from an organization", - "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations)\n", + "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9032,7 +9032,7 @@ "Config" ], "summary": "Retrieve feature flags", - "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/)\n", + "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9173,7 +9173,7 @@ "Tasks" ], "summary": "List all task members", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9218,7 +9218,7 @@ "Tasks" ], "summary": "Add a member to a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9276,7 +9276,7 @@ "Tasks" ], "summary": "Remove a member from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9325,7 +9325,7 @@ "Tasks" ], "summary": "List all owners of a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9386,7 +9386,7 @@ "Tasks" ], "summary": "Add an owner for a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9475,7 +9475,7 @@ "Tasks" ], "summary": "Remove an owner from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -11207,6 +11207,365 @@ } } }, + "/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 +11946,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", @@ -14302,7 +14401,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": [ @@ -14535,7 +14634,7 @@ "shardGroupDurationSeconds": { "type": "integer", "format": "int64", - "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration).\n" + "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration).\n" } }, "required": [ @@ -21979,7 +22078,7 @@ "type": "apiKey", "name": "Authorization", "in": "header", - "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB Cloud URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations)\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" + "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB Cloud URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))\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" }, "BasicAuthentication": { "type": "http", diff --git a/contracts/cloud.yml b/contracts/cloud.yml index b37c32df4..fad88d803 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -10,7 +10,7 @@ info: servers: - url: /api/v2 tags: - - name: Authorizations + - name: Authorizations (API tokens) description: | Create and manage authorizations (API tokens). @@ -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, @@ -5060,7 +5048,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5076,7 +5064,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -5141,7 +5129,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5156,7 +5144,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -5242,7 +5230,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5258,7 +5246,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -5736,7 +5724,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5833,7 +5821,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5933,7 +5921,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5994,7 +5982,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -6055,7 +6043,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -6065,7 +6053,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6140,7 +6128,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -6155,7 +6143,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7549,7 +7537,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/cloud/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/cloud/reference/config-options/#feature-flags). 3. **Optional**: To confirm that your change is applied, do one of the following: - Send a request to this endpoint to retrieve the current feature flag values. @@ -7558,7 +7546,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7689,7 +7677,7 @@ paths: summary: List all task members description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: @@ -7727,7 +7715,7 @@ paths: summary: Add a member to a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and then returns the member. @@ -7774,7 +7762,7 @@ paths: summary: Remove a member from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: @@ -7809,7 +7797,7 @@ paths: summary: List all owners of a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. parameters: @@ -7861,7 +7849,7 @@ paths: summary: Add an owner for a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. @@ -7938,7 +7926,7 @@ paths: summary: Remove an owner from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: @@ -9054,6 +9042,352 @@ 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 +9750,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 @@ -11617,7 +11731,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: @@ -11858,7 +11972,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/cloud/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -17168,7 +17282,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides diff --git a/contracts/common.yml b/contracts/common.yml index d81190c99..d145106df 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -4771,7 +4771,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -4787,7 +4787,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -4852,7 +4852,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -4867,7 +4867,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -4953,7 +4953,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -4969,7 +4969,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -5447,7 +5447,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5544,7 +5544,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5644,7 +5644,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5705,7 +5705,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -5766,7 +5766,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -5776,7 +5776,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -5851,7 +5851,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5866,7 +5866,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -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/latest/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/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/latest/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7400,7 +7400,7 @@ paths: summary: List all task members description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: @@ -7438,7 +7438,7 @@ paths: summary: Add a member to a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. @@ -7485,7 +7485,7 @@ paths: summary: Remove a member from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: @@ -7520,7 +7520,7 @@ paths: summary: List all owners of a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. parameters: @@ -7572,7 +7572,7 @@ paths: summary: Add an owner for a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. @@ -7649,7 +7649,7 @@ paths: summary: Remove an owner from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: @@ -8765,6 +8765,379 @@ 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: @@ -9537,7 +9910,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: @@ -9778,7 +10151,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: 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 d9f882296..81395bf17 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 @@ -5758,7 +5432,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). required: - everySeconds labels: @@ -5771,7 +5445,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: @@ -5794,7 +5478,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 @@ -6702,7 +6451,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides diff --git a/contracts/oss.json b/contracts/oss.json index 50f31e7ed..52ba5944f 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -16,8 +16,8 @@ ], "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" + "name": "Authorizations (API tokens)", + "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", @@ -6220,7 +6220,7 @@ "Buckets" ], "summary": "List all owners of a bucket", - "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6296,7 +6296,7 @@ "Buckets" ], "summary": "Add an owner to a bucket", - "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6394,7 +6394,7 @@ "Buckets" ], "summary": "Remove an owner from a bucket", - "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6950,7 +6950,7 @@ "Security and access endpoints" ], "summary": "List all members of an organization", - "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7051,7 +7051,7 @@ "Organizations" ], "summary": "Add a member to an organization", - "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7150,7 +7150,7 @@ "Security and access endpoints" ], "summary": "Remove a member from an organization", - "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7208,7 +7208,7 @@ "Security and access endpoints" ], "summary": "List all owners of an organization", - "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", + "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7282,7 +7282,7 @@ "Organizations" ], "summary": "Add an owner to an organization", - "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n", + "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7372,7 +7372,7 @@ "Security and access endpoints" ], "summary": "Remove an owner from an organization", - "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations)\n", + "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9033,7 +9033,7 @@ "Config" ], "summary": "Retrieve feature flags", - "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/)\n", + "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9174,7 +9174,7 @@ "Tasks" ], "summary": "List all task members", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9219,7 +9219,7 @@ "Tasks" ], "summary": "Add a member to a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9277,7 +9277,7 @@ "Tasks" ], "summary": "Remove a member from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9326,7 +9326,7 @@ "Tasks" ], "summary": "List all owners of a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9387,7 +9387,7 @@ "Tasks" ], "summary": "Add an owner for a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9476,7 +9476,7 @@ "Tasks" ], "summary": "Remove an owner from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -11208,6 +11208,365 @@ } } }, + "/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 +12827,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", @@ -16676,7 +16782,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": [ @@ -16909,7 +17015,7 @@ "shardGroupDurationSeconds": { "type": "integer", "format": "int64", - "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration).\n" + "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration).\n" } }, "required": [ @@ -24605,7 +24711,7 @@ "type": "apiKey", "name": "Authorization", "in": "header", - "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations)\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" + "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))\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" }, "BasicAuthentication": { "type": "http", diff --git a/contracts/oss.yml b/contracts/oss.yml index 52f678c27..e067b7240 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -10,7 +10,7 @@ info: servers: - url: /api/v2 tags: - - name: Authorizations + - name: Authorizations (API tokens) description: | Create and manage authorizations (API tokens). @@ -18,23 +18,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](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - In InfluxDB OSS, even if an API token has `read-authorizations` permission, the - token can't be used to view its authorization details. - We recommend creating a generic user to create and manage tokens for writing data. - #### User sessions with authorizations + ### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If a user signs in with username and password, creating a _user session_, @@ -104,7 +90,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -112,7 +98,7 @@ tags: - #### Related guides + ### Related guides - [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/) @@ -136,7 +122,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) @@ -147,14 +133,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](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) @@ -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, @@ -5050,7 +5036,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5066,7 +5052,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -5131,7 +5117,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5146,7 +5132,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -5232,7 +5218,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5248,7 +5234,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -5726,7 +5712,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5823,7 +5809,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5923,7 +5909,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -5984,7 +5970,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -6045,7 +6031,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -6055,7 +6041,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6130,7 +6116,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -6145,7 +6131,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -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/latest/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/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/latest/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7679,7 +7665,7 @@ paths: summary: List all task members description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: @@ -7717,7 +7703,7 @@ paths: summary: Add a member to a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. @@ -7764,7 +7750,7 @@ paths: summary: Remove a member from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: @@ -7799,7 +7785,7 @@ paths: summary: List all owners of a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. parameters: @@ -7851,7 +7837,7 @@ paths: summary: Add an owner for a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. @@ -7928,7 +7914,7 @@ paths: summary: Remove an owner from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: @@ -9044,6 +9030,352 @@ 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 @@ -10258,216 +10590,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/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. - - #### Required permissions - - - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - - #### 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). - 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/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 - - 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/latest/security/tokens/#operator-token)_. - - You can't update an authorization's permissions. - - Even if an API token has `read-authorizations` permission, the - token can't be used to view its authorization details. - - A token stops working when the user who created the authorization is deleted. - - We recommend creating a generic user to create and manage tokens for writing data. - - #### 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 - - 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 @@ -13190,7 +13312,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: @@ -13431,7 +13553,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -18900,7 +19022,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides diff --git a/contracts/priv/cloud-priv.yml b/contracts/priv/cloud-priv.yml index cd90b87d7..ab9c6e327 100644 --- a/contracts/priv/cloud-priv.yml +++ b/contracts/priv/cloud-priv.yml @@ -847,7 +847,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). required: - everySeconds labels: @@ -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 48e47a110..474b18f2b 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: @@ -4011,7 +4012,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/cloud/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -6723,7 +6724,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides @@ -6769,7 +6770,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 @@ -6779,7 +6780,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 @@ -6789,39 +6794,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: @@ -6832,7 +6844,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 @@ -6845,7 +6869,8 @@ paths: description: Unexpected error summary: List authorizations tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints post: description: | Creates an authorization and returns the authorization with the @@ -6853,20 +6878,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 @@ -6895,7 +6924,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 @@ -6908,13 +6938,21 @@ paths: description: Unexpected error summary: Create an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/authorizations/{authID}: delete: + description: | + Deletes an authorization. + + Use the endpoint to delete an API token. + + If you want to disable an API token instead of delete it, + [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the authorization to delete. + - description: An authorization ID. Specifies the authorization to delete. in: path name: authID required: true @@ -6922,18 +6960,70 @@ paths: type: string responses: "204": - description: Authorization deleted + description: Success. The authorization is deleted. + "400": + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + "401": + $ref: '#/components/responses/AuthorizationError' + "404": + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + "500": + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints get: + description: | + Retrieves an authorization. + + Use this endpoint to retrieve information about an API token, including + the token's permissions and the user that the token is scoped to. + + #### InfluxDB OSS + + - InfluxDB OSS returns + [API token](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 @@ -6945,19 +7035,56 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Authorization details + description: Success. The response body contains the authorization. + "400": + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + "401": + $ref: '#/components/responses/AuthorizationError' + "404": + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + "500": + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints patch: - description: Update an authorization's status to `active` or `inactive`. + description: | + Updates an authorization. + + Use this endpoint to set an API token's status to be _active_ or _inactive_. + InfluxDB rejects requests that use inactive API tokens. operationId: PatchAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the authorization to update. + - description: An authorization ID. Specifies the authorization to update. in: path name: authID required: true @@ -6968,7 +7095,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": @@ -6976,13 +7104,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: The updated authorization. + description: Success. The response body contains the updated authorization. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: Update authorization status + summary: Update an API token to be active or inactive tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/buckets: get: description: | @@ -7986,7 +8115,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8002,7 +8131,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8067,7 +8196,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8082,7 +8211,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8168,7 +8297,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8184,7 +8313,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -10125,7 +10254,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/cloud/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/cloud/reference/config-options/#feature-flags). 3. **Optional**: To confirm that your change is applied, do one of the following: - Send a request to this endpoint to retrieve the current feature flag values. @@ -10134,7 +10263,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11436,7 +11565,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11534,7 +11663,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11633,7 +11762,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11694,7 +11823,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -11756,7 +11885,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -11766,7 +11895,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: PostOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11840,7 +11969,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -11855,7 +11984,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15607,7 +15736,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: GetTasksIDMembers @@ -15645,7 +15774,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and then returns the member. @@ -15692,7 +15821,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: DeleteTasksIDMembersID @@ -15728,7 +15857,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. operationId: GetTasksIDOwners @@ -15780,7 +15909,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. @@ -15857,7 +15986,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: DeleteTasksIDOwnersID @@ -18656,24 +18785,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_, @@ -18691,7 +18808,7 @@ tags: - [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication) - [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/) - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) - name: Authorizations + name: Authorizations (API tokens) - description: | Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets @@ -18721,7 +18838,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) @@ -18750,7 +18867,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -18758,7 +18875,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/) @@ -18781,7 +18898,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/) @@ -18796,14 +18913,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 @@ -18878,7 +18995,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 adb370b8c..eb6911a97 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -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 @@ -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: @@ -3984,7 +3985,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -6768,7 +6769,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides @@ -6816,16 +6817,19 @@ paths: To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations. - #### InfluxDB OSS + #### InfluxDB Cloud - - InfluxDB OSS returns - [API token](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. + - 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 @@ -6860,13 +6864,44 @@ paths: 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 @@ -6879,7 +6914,7 @@ paths: description: Unexpected error summary: List authorizations tags: - - Authorizations + - Authorizations (API tokens) - Security and access endpoints post: description: | @@ -6888,21 +6923,24 @@ paths: Use this endpoint to create an authorization, which generates an API token with permissions to `read` or `write` to a specific resource or `type` of resource. - The response contains the new authorization with the generated API token. - - #### Limitations + The API token is the authorization's `token` property value. To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens. - - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any - user with an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - - You can't update an authorization's permissions. - - Even if an API token has `read-authorizations` permission, the - token can't be used to view its authorization details. - - A token stops working when the user who created the authorization is deleted. + - InfluxDB allows access to the API token value immediately after the authorization is created. + - You can’t change access (read/write) permissions for an API token after it’s created. + - Tokens stop working when the user who created the token is deleted. - We recommend creating a generic user to create and manage tokens for writing data. + We recommend the following for managing your tokens: + + - Create a generic user to create and manage tokens for writing data. + - Store your tokens in a secure password vault for future access. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to #### Related guides @@ -6931,7 +6969,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 @@ -6944,13 +6983,21 @@ paths: description: Unexpected error summary: Create an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/authorizations/{authID}: delete: + description: | + Deletes an authorization. + + Use the endpoint to delete an API token. + + If you want to disable an API token instead of delete it, + [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to delete. + - description: An authorization ID. Specifies the authorization to delete. in: path name: authID required: true @@ -6958,18 +7005,70 @@ paths: type: string responses: "204": - description: Authorization deleted + description: Success. The authorization is deleted. + "400": + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + "401": + $ref: '#/components/responses/AuthorizationError' + "404": + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + "500": + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints get: + description: | + Retrieves an authorization. + + Use this endpoint to retrieve information about an API token, including + the token's permissions and the user that the token is scoped to. + + #### InfluxDB OSS + + - InfluxDB OSS returns + [API token](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 +7080,56 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Authorization details + description: Success. The response body contains the authorization. + "400": + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + "401": + $ref: '#/components/responses/AuthorizationError' + "404": + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + "500": + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: - - Authorizations + - Authorizations (API tokens) - Security and access endpoints patch: + description: | + Updates an authorization. + + Use this endpoint to set an API token's status to be _active_ or _inactive_. + InfluxDB rejects requests that use inactive API tokens. operationId: PatchAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to update. + - description: An authorization ID. Specifies the authorization to update. in: path name: authID required: true @@ -7004,7 +7140,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 +7149,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: The active or inactive authorization + description: Success. The response body contains the updated authorization. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: Update an authorization to be active or inactive + summary: Update an API token to be active or inactive tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints /api/v2/backup/kv: get: deprecated: true @@ -8156,7 +8294,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8172,7 +8310,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8237,7 +8375,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8252,7 +8390,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -8338,7 +8476,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -8354,7 +8492,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -10662,7 +10800,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/latest/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/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 +10809,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12028,7 +12166,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12126,7 +12264,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12225,7 +12363,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12286,7 +12424,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -12348,7 +12486,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -12358,7 +12496,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: PostOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12432,7 +12570,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -12447,7 +12585,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16443,7 +16581,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: GetTasksIDMembers @@ -16481,7 +16619,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns the member. @@ -16528,7 +16666,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDMembersID @@ -16564,7 +16702,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. operationId: GetTasksIDOwners @@ -16616,7 +16754,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. @@ -16693,7 +16831,7 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: DeleteTasksIDOwnersID @@ -19526,23 +19664,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](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. - In InfluxDB OSS, even if an API token has `read-authorizations` permission, the - token can't be used to view its authorization details. - We recommend creating a generic user to create and manage tokens for writing data. - #### User sessions with authorizations + ### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If a user signs in with username and password, creating a _user session_, @@ -19560,7 +19684,7 @@ tags: - [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 + name: Authorizations (API tokens) - description: | 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 @@ -19612,7 +19736,7 @@ tags: - #### Properties + ### Properties A `task` object contains information about an InfluxDB task resource. @@ -19620,7 +19744,7 @@ tags: - #### Related guides + ### Related guides - [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/) @@ -19644,7 +19768,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides + ### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) @@ -19655,14 +19779,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](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) @@ -19738,7 +19862,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..4d31d27d2 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}': @@ -136,7 +132,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides 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..a491632bc 100644 --- a/src/cloud/tags.yml +++ b/src/cloud/tags.yml @@ -1,5 +1,5 @@ tags: - - name: Authorizations + - name: Authorizations (API tokens) description: | Create and manage authorizations (API tokens). @@ -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..5dd7be749 100644 --- a/src/common/paths/authorizations.yml +++ b/src/common/paths/authorizations.yml @@ -1,7 +1,7 @@ get: operationId: GetAuthorizations tags: - - Authorizations + - Authorizations (API tokens) - Security and access endpoints summary: List authorizations description: | @@ -10,16 +10,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 +57,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: @@ -74,7 +108,8 @@ get: post: operationId: PostAuthorizations tags: - - Authorizations + - Authorizations (API tokens) + - Security and access endpoints summary: Create an authorization description: | Creates an authorization and returns the authorization with the @@ -82,21 +117,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 +158,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..a31a0d782 100644 --- a/src/common/paths/authorizations_authID.yml +++ b/src/common/paths/authorizations_authID.yml @@ -1,9 +1,28 @@ get: operationId: GetAuthorizationsID tags: - - Authorizations + - 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,24 +30,64 @@ 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' patch: operationId: PatchAuthorizationsID tags: - - Authorizations - summary: Update an authorization to be active or inactive + - 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: Authorization to update + description: In the request body, provide the authorization properties to update. required: true content: application/json: @@ -41,10 +100,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: @@ -55,8 +114,16 @@ patch: delete: operationId: DeleteAuthorizationsID tags: - - Authorizations + - 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 +131,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/paths/buckets_bucketID_owners.yml b/src/common/paths/buckets_bucketID_owners.yml index 13daf62b9..6c324a1de 100644 --- a/src/common/paths/buckets_bucketID_owners.yml +++ b/src/common/paths/buckets_bucketID_owners.yml @@ -13,7 +13,7 @@ get: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -29,7 +29,7 @@ get: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides @@ -84,7 +84,7 @@ post: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -99,7 +99,7 @@ post: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides diff --git a/src/common/paths/buckets_bucketID_owners_userID.yml b/src/common/paths/buckets_bucketID_owners_userID.yml index e07b24e8b..1f1880642 100644 --- a/src/common/paths/buckets_bucketID_owners_userID.yml +++ b/src/common/paths/buckets_bucketID_owners_userID.yml @@ -11,7 +11,7 @@ delete: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -27,7 +27,7 @@ delete: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides diff --git a/src/common/paths/flags.yml b/src/common/paths/flags.yml index 6154641be..3fe197944 100644 --- a/src/common/paths/flags.yml +++ b/src/common/paths/flags.yml @@ -14,7 +14,7 @@ get: 1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve feature flags and their values. - 2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/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. @@ -23,7 +23,7 @@ get: #### Related guides - - [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/) + - [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/) parameters: - $ref: "../parameters/TraceSpan.yml" responses: diff --git a/src/common/paths/orgs_orgID_members.yml b/src/common/paths/orgs_orgID_members.yml index 64a3e3b19..c91c14a1b 100644 --- a/src/common/paths/orgs_orgID_members.yml +++ b/src/common/paths/orgs_orgID_members.yml @@ -16,7 +16,7 @@ get: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -99,7 +99,7 @@ post: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations diff --git a/src/common/paths/orgs_orgID_members_userID.yml b/src/common/paths/orgs_orgID_members_userID.yml index 9c3b66de7..4f149fd44 100644 --- a/src/common/paths/orgs_orgID_members_userID.yml +++ b/src/common/paths/orgs_orgID_members_userID.yml @@ -14,7 +14,7 @@ delete: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations diff --git a/src/common/paths/orgs_orgID_owners.yml b/src/common/paths/orgs_orgID_owners.yml index 001c1ee57..9d1f3f586 100644 --- a/src/common/paths/orgs_orgID_owners.yml +++ b/src/common/paths/orgs_orgID_owners.yml @@ -10,7 +10,7 @@ get: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -61,7 +61,7 @@ post: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions @@ -71,7 +71,7 @@ post: #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: "../parameters/TraceSpan.yml" - in: path diff --git a/src/common/paths/orgs_orgID_owners_userID.yml b/src/common/paths/orgs_orgID_owners_userID.yml index 1d5320c01..bdfa0f626 100644 --- a/src/common/paths/orgs_orgID_owners_userID.yml +++ b/src/common/paths/orgs_orgID_owners_userID.yml @@ -13,7 +13,7 @@ delete: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations @@ -28,7 +28,7 @@ delete: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations) + - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: "../parameters/TraceSpan.yml" - in: path diff --git a/src/common/paths/tasks_taskID_members.yml b/src/common/paths/tasks_taskID_members.yml index 66917b463..479c4ef4f 100644 --- a/src/common/paths/tasks_taskID_members.yml +++ b/src/common/paths/tasks_taskID_members.yml @@ -6,7 +6,7 @@ get: summary: List all task members description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: @@ -44,7 +44,7 @@ post: summary: Add a member to a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns the member. diff --git a/src/common/paths/tasks_taskID_members_userID.yml b/src/common/paths/tasks_taskID_members_userID.yml index 402ccd146..abc08c313 100644 --- a/src/common/paths/tasks_taskID_members_userID.yml +++ b/src/common/paths/tasks_taskID_members_userID.yml @@ -6,7 +6,7 @@ delete: summary: Remove a member from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: diff --git a/src/common/paths/tasks_taskID_owners.yml b/src/common/paths/tasks_taskID_owners.yml index 10e092c6c..874137695 100644 --- a/src/common/paths/tasks_taskID_owners.yml +++ b/src/common/paths/tasks_taskID_owners.yml @@ -6,7 +6,7 @@ get: summary: List all owners of a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `owner` role for the specified task. parameters: @@ -58,7 +58,7 @@ post: summary: Add an owner for a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a specified user to owners of the specified task and then returns the owner. diff --git a/src/common/paths/tasks_taskID_owners_userID.yml b/src/common/paths/tasks_taskID_owners_userID.yml index d8db0f5bc..7f65d1280 100644 --- a/src/common/paths/tasks_taskID_owners_userID.yml +++ b/src/common/paths/tasks_taskID_owners_userID.yml @@ -6,7 +6,7 @@ delete: summary: Remove an owner from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: 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/common/schemas/RetentionRule.yml b/src/common/schemas/RetentionRule.yml index 68bd9ca51..eff37f335 100644 --- a/src/common/schemas/RetentionRule.yml +++ b/src/common/schemas/RetentionRule.yml @@ -29,5 +29,5 @@ #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). required: [everySeconds] 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..d9715ab57 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}": @@ -225,7 +221,7 @@ components: # # For more information and examples, see the following: # - # - [`/authorizations`(#tag/Authorizations) endpoints] + # - [`/authorizations`(#tag/Authorizations-(API-tokens)) endpoints] # - [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication) # - [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/) TokenAuthentication: @@ -262,7 +258,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations) + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides diff --git a/src/oss/tags.yml b/src/oss/tags.yml index 5879b2864..739fcf547 100644 --- a/src/oss/tags.yml +++ b/src/oss/tags.yml @@ -1,5 +1,5 @@ tags: - - name: Authorizations + - name: Authorizations (API tokens) description: | Create and manage authorizations (API tokens). @@ -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,