openapi: 3.0.0 info: title: Complete InfluxDB Cloud Authorizations (API tokens) Authorizations (API tokens) Authorizations (API tokens) API 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/) ' servers: - url: '' security: - TokenAuthentication: [] tags: - 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/) ' name: Authorizations (API tokens) paths: /api/v2/authorizations: get: 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" operationId: GetAuthorizations parameters: - $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). ' 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). ' 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). 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). ' in: query name: org 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" 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.\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" '400': $ref: '#/components/responses/GeneralServerError' description: Invalid request '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: List authorizations tags: - Authorizations (API tokens) post: 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" operationId: PostAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: content: application/json: examples: AuthorizationPostRequest: $ref: '#/components/examples/AuthorizationPostRequest' AuthorizationWithResourcePostRequest: $ref: '#/components/examples/AuthorizationWithResourcePostRequest' AuthorizationWithUserPostRequest: $ref: '#/components/examples/AuthorizationWithUserPostRequest' schema: $ref: '#/components/schemas/AuthorizationPostRequest' description: The authorization to create. required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/Authorization' description: 'Success. The authorization is created. The response body contains the authorization. ' '400': $ref: '#/components/responses/GeneralServerError' description: Invalid request '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create an authorization tags: - Authorizations (API tokens) /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: An authorization ID. Specifies the authorization to delete. in: path name: authID required: true schema: type: string responses: '204': description: Success. The authorization is deleted. '400': content: application/json: examples: notFound: summary: 'The specified resource ID is invalid. ' value: code: invalid message: id must have a length of 16 bytes schema: $ref: '#/components/schemas/Error' description: 'Bad request. ' '401': $ref: '#/components/responses/AuthorizationError' '404': content: application/json: examples: notFound: summary: 'The requested authorization doesn''t exist. ' value: code: not found message: authorization not found schema: $ref: '#/components/schemas/Error' description: 'Not found. ' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: - Authorizations (API tokens) get: 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: description: View tokens url: https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/ operationId: GetAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - description: An authorization ID. Specifies the authorization to retrieve. in: path name: authID required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Authorization' description: Success. The response body contains the authorization. '400': content: application/json: examples: notFound: summary: 'The specified resource ID is invalid. ' value: code: invalid message: id must have a length of 16 bytes schema: $ref: '#/components/schemas/Error' description: 'Bad request. ' '401': $ref: '#/components/responses/AuthorizationError' '404': content: application/json: examples: notFound: summary: 'The requested authorization doesn''t exist. ' value: code: not found message: authorization not found schema: $ref: '#/components/schemas/Error' description: 'Not found. ' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: - Authorizations (API tokens) 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: An authorization ID. Specifies the authorization to update. in: path name: authID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthorizationUpdateRequest' description: In the request body, provide the authorization properties to update. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Authorization' description: Success. The response body contains the updated authorization. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Update an API token to be active or inactive tags: - Authorizations (API tokens) components: schemas: Permission: properties: action: enum: - read - write type: string resource: $ref: '#/components/schemas/Resource' properties: id: description: 'A resource ID. Identifies a specific resource. ' type: string name: description: 'The name of the resource. _Note: not all resource types have a `name` property_. ' type: string org: description: 'An organization name. The organization that owns the resource. ' type: string orgID: description: 'An organization ID. Identifies the organization that owns the resource. ' type: string type: description: 'A resource type. Identifies the API resource''s type (or _kind_). ' 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 type: string required: - type type: object required: - action - resource Links: description: 'URI pointers for additional paged results. ' properties: next: $ref: '#/components/schemas/Link' prev: $ref: '#/components/schemas/Link' self: $ref: '#/components/schemas/Link' required: - self type: object Resource: properties: id: description: 'A resource ID. Identifies a specific resource. ' type: string name: description: 'The name of the resource. _Note: not all resource types have a `name` property_. ' type: string org: description: 'An organization name. The organization that owns the resource. ' type: string orgID: description: 'An organization ID. Identifies the organization that owns the resource. ' type: string type: description: 'A resource type. Identifies the API resource''s type (or _kind_). ' 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 type: string required: - type type: object Authorization: allOf: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - properties: createdAt: format: date-time readOnly: true type: string id: description: The authorization ID. readOnly: true type: string links: example: self: /api/v2/authorizations/1 user: /api/v2/users/12 properties: self: $ref: '#/components/schemas/Link' readOnly: true user: $ref: '#/components/schemas/Link' readOnly: true readOnly: true type: object org: description: 'The organization name. Specifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that the token is scoped to. ' readOnly: true type: string orgID: description: 'The organization ID. Specifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that the authorization is scoped to. ' type: string permissions: description: 'The list of permissions. An authorization must have at least one permission. ' items: $ref: '#/components/schemas/Permission' minItems: 1 type: array token: description: 'The API token. The token value is unique to the authorization. [API tokens]({{% INFLUXDB_DOCS_URL %}}/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). ' readOnly: true type: string updatedAt: format: date-time readOnly: true type: string user: description: 'The user name. Specifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the authorization. If the authorization is _scoped_ to a user, the user; otherwise, the creator of the authorization. ' readOnly: true type: string userID: description: The user ID. Specifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization. readOnly: true type: string type: object required: - orgID - permissions Link: description: URI of resource. format: uri readOnly: true type: string Authorizations: properties: authorizations: items: $ref: '#/components/schemas/Authorization' type: array links: $ref: '#/components/schemas/Links' readOnly: true type: object ErrorCode: description: code is the machine-readable error code. 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 readOnly: true type: string AuthorizationUpdateRequest: properties: description: description: A description of the token. type: string status: default: active description: Status of the token. If `inactive`, InfluxDB rejects requests that use the token. enum: - active - inactive type: string AuthorizationPostRequest: allOf: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - properties: orgID: description: 'An organization ID. Specifies the organization that owns the authorization. ' type: string permissions: 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' minItems: 1 type: array userID: 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. ' type: string type: object required: - orgID - permissions Error: properties: code: $ref: '#/components/schemas/ErrorCode' description: code is the machine-readable error code. 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 readOnly: true type: string err: description: Stack of errors that occurred during processing of the request. Useful for debugging. readOnly: true type: string message: description: Human-readable message. readOnly: true type: string op: description: Describes the logical code operation when the error occurred. Useful for debugging. readOnly: true type: string required: - code responses: AuthorizationError: content: application/json: examples: tokenNotAuthorized: summary: Token is not authorized to access a resource value: code: unauthorized message: unauthorized access schema: properties: code: description: 'The HTTP status code description. Default is `unauthorized`. ' enum: - unauthorized readOnly: true type: string message: description: A human-readable message that may contain detail about the error. readOnly: true type: string 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" GeneralServerError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Non 2XX error response from server. InternalServerError: content: application/json: schema: $ref: '#/components/schemas/Error' description: 'Internal server error. The server encountered an unexpected situation. ' examples: AuthorizationWithUserPostRequest: description: Creates an authorization scoped to a specific user. summary: An authorization scoped to a user value: description: iot_user write to bucket orgID: INFLUX_ORG_ID permissions: - action: write resource: id: INFLUX_BUCKET_ID type: buckets userID: INFLUX_USER_ID AuthorizationPostRequest: description: Creates an authorization. summary: An authorization for a resource type value: description: iot_users read buckets orgID: INFLUX_ORG_ID permissions: - action: read resource: type: buckets AuthorizationWithResourcePostRequest: description: Creates an authorization for access to a specific resource. summary: An authorization for a resource value: description: iot_users read buckets orgID: INFLUX_ORG_ID permissions: - action: read resource: id: INFLUX_BUCKET_ID type: buckets parameters: TraceSpan: description: OpenTracing span context example: baggage: key: value span_id: '1' trace_id: '1' in: header name: Zap-Trace-Span required: false schema: type: string securitySchemes: BasicAuthentication: 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" scheme: basic type: http TokenAuthentication: 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" in: header name: Authorization type: apiKey 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: []