InfluxData Authorizations (API tokens) API

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: []