openapi: 3.0.0 info: title: InfluxDB Cloud API Service Authorizations (API tokens) Authorizations (API tokens) Authorizations (API tokens) API version: 2.0.1 description: 'The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. ' license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: /api/v2 security: - TokenAuthentication: [] tags: - name: Authorizations (API tokens) description: 'Create and manage authorizations (API tokens). An _authorization_ contains a list of `read` and `write` permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. 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 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_, the session carries the permissions granted by all the user''s authorizations. For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/). To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints - [Signin](#tag/Signin) - [Signout](#tag/Signout) ### Related guides - [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/) ' paths: /authorizations: get: operationId: GetAuthorizations tags: - Authorizations (API tokens) 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](https://docs.influxdata.com/influxdb/cloud/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](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/)\n" 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.\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](https://docs.influxdata.com/influxdb/cloud/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) summary: Create an authorization description: "Creates an authorization and returns the authorization with the\ngenerated API [token](https://docs.influxdata.com/influxdb/cloud/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](https://docs.influxdata.com/influxdb/cloud/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. ' 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) 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](https://docs.influxdata.com/influxdb/cloud/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](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/)\n" 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) 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) 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: responses: AuthorizationError: description: "Unauthorized. The error may indicate one of the following:\n\n * The `Authorization: Token` header is missing or malformed.\n * The API token value is missing from the header.\n * The token doesn't have sufficient permissions to write to this organization and bucket.\n" content: application/json: schema: properties: code: description: 'The HTTP status code description. Default is `unauthorized`. ' readOnly: true type: string enum: - unauthorized message: readOnly: true description: A human-readable message that may contain detail about the error. type: string examples: tokenNotAuthorized: summary: Token is not authorized to access a resource value: code: unauthorized message: unauthorized access GeneralServerError: description: Non 2XX error response from server. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: 'Internal server error. The server encountered an unexpected situation. ' content: application/json: schema: $ref: '#/components/schemas/Error' schemas: AuthorizationUpdateRequest: 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. AuthorizationPostRequest: required: - orgID - permissions allOf: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - 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: $ref: '#/components/schemas/Permission' 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. ' Permission: required: - action - resource properties: action: type: string enum: - read - write resource: $ref: '#/components/schemas/Resource' Links: type: object description: 'URI pointers for additional paged results. ' properties: next: $ref: '#/components/schemas/Link' self: $ref: '#/components/schemas/Link' prev: $ref: '#/components/schemas/Link' required: - self Authorizations: type: object properties: links: readOnly: true $ref: '#/components/schemas/Links' authorizations: type: array items: $ref: '#/components/schemas/Authorization' Link: type: string format: uri readOnly: true description: URI of resource. Error: properties: code: description: code is the machine-readable error code. readOnly: true type: string enum: - internal error - not implemented - not found - conflict - invalid - unprocessable entity - empty value - unavailable - forbidden - too many requests - unauthorized - method not allowed - request too large - unsupported media type message: readOnly: true description: Human-readable message. type: string op: readOnly: true description: Describes the logical code operation when the error occurred. Useful for debugging. type: string err: readOnly: true description: Stack of errors that occurred during processing of the request. Useful for debugging. type: string required: - code Authorization: required: - orgID - permissions allOf: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - type: object properties: createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true orgID: type: string description: 'The organization ID. Specifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that the authorization is scoped to. ' permissions: type: array minItems: 1 description: 'The list of permissions. An authorization must have at least one permission. ' items: $ref: '#/components/schemas/Permission' id: readOnly: true type: string description: The authorization ID. token: readOnly: true type: string description: 'The API token. The token value is unique to the authorization. [API tokens](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx` CLI commands--after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). ' userID: readOnly: true type: string description: The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization. user: readOnly: true type: string description: 'The user name. Specifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the authorization. If the authorization is _scoped_ to a user, the user; otherwise, the creator of the authorization. ' org: readOnly: true type: string description: 'The organization name. Specifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that the token is scoped to. ' links: type: object readOnly: true example: self: /api/v2/authorizations/1 user: /api/v2/users/12 properties: self: readOnly: true $ref: '#/components/schemas/Link' user: readOnly: true $ref: '#/components/schemas/Link' 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 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 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 parameters: TraceSpan: in: header name: Zap-Trace-Span description: OpenTracing span context example: trace_id: '1' span_id: '1' baggage: key: value required: false schema: type: string securitySchemes: TokenAuthentication: 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))\n\n### Related guides\n\n- [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication)\n- [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/)\n" BasicAuthentication: type: http scheme: basic description: "### Basic authentication scheme\n\nUse the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it:\n\n### Syntax\n\n`Authorization: Basic BASE64_ENCODED_CREDENTIALS`\n\nTo construct the `BASE64_ENCODED_CREDENTIALS`, combine the username and\nthe password with a colon (`USERNAME:PASSWORD`), and then encode the\nresulting string in [base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64).\nMany HTTP clients encode the credentials for you before sending the\nrequest.\n\n_**Warning**: Base64-encoding can easily be reversed to obtain the original\nusername and password. It is used to keep the data intact and does not provide\nsecurity. You should always use HTTPS when authenticating or sending a request with\nsensitive information._\n\n### Examples\n\nIn the examples, replace the following:\n\n- **`EMAIL_ADDRESS`**: InfluxDB Cloud username (the email address the user signed up with)\n- **`PASSWORD`**: InfluxDB Cloud [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)\n- **`INFLUX_URL`**: your InfluxDB Cloud URL\n\n#### Encode credentials with cURL\n\nThe following example shows how to use cURL to send an API request that uses Basic authentication.\nWith the `--user` option, cURL encodes the credentials and passes them\nin the `Authorization: Basic` header.\n\n```sh\ncurl --get \"INFLUX_URL/api/v2/signin\"\n --user \"EMAIL_ADDRESS\":\"PASSWORD\"\n```\n\n#### Encode credentials with Flux\n\nThe Flux [`http.basicAuth()` function](https://docs.influxdata.com/flux/v0.x/stdlib/http/basicauth/) returns a Base64-encoded\nbasic authentication header using a specified username and password combination.\n\n#### Encode credentials with JavaScript\n\nThe following example shows how to use the JavaScript `btoa()` function\nto create a Base64-encoded string:\n\n```js\nbtoa('EMAIL_ADDRESS:PASSWORD')\n```\n\nThe output is the following:\n\n```js\n'VVNFUk5BTUU6UEFTU1dPUkQ='\n```\n\nOnce you have the Base64-encoded credentials, you can pass them in the\n`Authorization` header--for example:\n\n```sh\ncurl --get \"INFLUX_URL/api/v2/signin\"\n --header \"Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQ=\"\n```\n\nTo learn more about HTTP authentication, see\n[Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)._\n" x-tagGroups: - name: Overview tags: - Quick start - Authentication - Supported operations - Headers - Pagination - Response codes - name: Popular endpoints tags: - Data I/O endpoints - Security and access endpoints - System information endpoints - name: All endpoints tags: []