openapi: 3.0.0 info: title: InfluxDB Cloud API Service Authorizations (API tokens) Authorizations (API tokens) Security and access endpoints 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: Security and access endpoints paths: /signin: post: operationId: PostSignin summary: Create a user session. description: "Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication)\nfor a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user),\nand then, if successful, generates a user session.\n\nTo authenticate a user, pass the HTTP `Authorization` header with the\n`Basic` scheme and the base64-encoded username and password.\nFor syntax and more information, see [Basic Authentication](#section/Authentication/BasicAuthentication) for\nsyntax and more information.\n\nIf authentication is successful, InfluxDB creates a new session for the user\nand then returns the session cookie in the `Set-Cookie` response header.\n\nInfluxDB stores user sessions in memory only.\nThey expire within ten minutes and during restarts of the InfluxDB instance.\n\n#### User sessions with authorizations\n\n- In InfluxDB Cloud, a user session inherits all the user's permissions for\n the organization.\n- In InfluxDB OSS, a user session inherits all the user's permissions for all\n the organizations that the user belongs to.\n\n#### Related endpoints\n\n- [Signout](#tag/Signout)\n" tags: - Security and access endpoints security: - BasicAuthentication: [] parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': description: 'Success. The user is authenticated. The `Set-Cookie` response header contains the session cookie. ' '401': description: 'Unauthorized. This error may be caused by one of the following problems: - The user doesn''t have access. - The user passed incorrect credentials in the request. - The credentials are formatted incorrectly in the request. ' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden. The user account is disabled. content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unsuccessful authentication. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: 'cURL: signin with --user option encoding' source: "curl --request POST http://localhost:8086/api/v2/signin \\\n --user \"USERNAME:PASSWORD\"\n" /signout: post: operationId: PostSignout summary: Expire a user session tags: - Security and access endpoints description: "Expires a user session specified by a session cookie.\n\nUse this endpoint to expire a user session that was generated when the user\nauthenticated with the InfluxDB Developer Console (UI) or the `POST /api/v2/signin` endpoint.\n\nFor example, the `POST /api/v2/signout` endpoint represents the third step\nin the following three-step process\nto authenticate a user, retrieve the `user` resource, and then expire the session:\n\n1. Send a request with the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication)\n to the `POST /api/v2/signin` endpoint to create a user session and\n generate a session cookie.\n2. Send a request to the `GET /api/v2/me` endpoint, passing the stored session cookie\n from step 1 to retrieve user information.\n3. Send a request to the `POST /api/v2/signout` endpoint, passing the stored session\n cookie to expire the session.\n\n_See the complete example in request samples._\n\nInfluxDB stores user sessions in memory only.\nIf a user doesn't sign out, then the user session automatically expires within ten minutes or\nduring a restart of the InfluxDB instance.\n\nTo learn more about cookies in HTTP requests, see\n[Mozilla Developer Network (MDN) Web Docs, HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies).\n\n#### Related endpoints\n\n- [Signin](#tag/Signin)\n" parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': description: Success. The session is expired. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' default: description: The session expiry is unsuccessful. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: 'cURL: sign in a user, verify the user session, and then end the session' source: "# The following example shows how to use cURL and the InfluxDB API\n# to do the following:\n# 1. Sign in a user with a username and password.\n# 2. Check that the user session exists for the user.\n# 3. Sign out the user to expire the session.\n# 4. Check that the session is no longer active.\n\n# 1. Send a request to `POST /api/v2/signin` to sign in the user.\n# In your request, pass the following:\n#\n# - `--user` option with basic authentication credentials.\n# - `-c` option with a file path where cURL will write cookies.\n\n curl --request POST \\\n -c ./cookie-file.tmp \\\n \"$INFLUX_URL/api/v2/signin\" \\\n --user \"${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}\"\n\n# 2. To check that a user session exists for the user in step 1,\n# send a request to `GET /api/v2/me`.\n# In your request, pass the `-b` option with the session cookie file path from step 1.\n\n curl --request GET \\\n -b ./cookie-file.tmp \\\n \"$INFLUX_URL/api/v2/me\"\n\n# InfluxDB responds with the `user` resource.\n\n# 3. Send a request to `POST /api/v2/signout` to expire the user session.\n# In your request, pass the `-b` option with the session cookie file path from step 1.\n\n curl --request POST \\\n -b ./cookie-file.tmp \\\n \"$INFLUX_URL/api/v2/signout\"\n\n# If the user session is successfully expired, InfluxDB responds with\n an HTTP `204` status code.\n\n# 4. To check that the user session is expired, call `GET /api/v2/me` again,\n# passing the `-b` option with the cookie file path.\n\n curl --request GET \\\n -b ./cookie-file.tmp \\\n \"$INFLUX_URL/api/v2/me\"\n\n# If the user session is expired, InfluxDB responds with an HTTP `401` status code.\n" /orgs: get: operationId: GetOrgs tags: - Security and access endpoints summary: List organizations description: 'Lists [organizations](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization/). To limit which organizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. #### InfluxDB Cloud - Only returns the organization that owns the token passed in the request. #### Related guides - [View organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/) ' parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Descending' - in: query name: org schema: type: string description: 'An organization name. Only returns the specified organization. ' - in: query name: orgID schema: type: string description: 'An organization ID. Only returns the specified organization. ' - in: query name: userID schema: type: string description: 'A user ID. Only returns organizations where the specified user is a member or owner. ' responses: '200': description: Success. The response body contains a list of organizations. content: application/json: schema: $ref: '#/components/schemas/Organizations' examples: successResponse: value: links: self: /api/v2/orgs orgs: - links: buckets: /api/v2/buckets?org=INFLUX_ORG dashboards: /api/v2/dashboards?org=INFLUX_ORG labels: /api/v2/orgs/INFLUX_ORG_ID/labels logs: /api/v2/orgs/INFLUX_ORG_ID/logs members: /api/v2/orgs/INFLUX_ORG_ID/members owners: /api/v2/orgs/INFLUX_ORG_ID/owners secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets self: /api/v2/orgs/INFLUX_ORG_ID tasks: /api/v2/tasks?org=InfluxData id: INFLUX_ORG_ID name: INFLUX_ORG description: Example InfluxDB organization createdAt: '2022-07-17T23:00:30.778487Z' updatedAt: '2022-07-17T23:00:30.778487Z' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' /orgs/{orgID}: get: operationId: GetOrgsID tags: - Security and access endpoints summary: Retrieve an organization description: 'Retrieves an organization. Use this endpoint to retrieve information for a specific organization. #### Related guides - [View organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/) ' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: 'The ID of the organization to retrieve. ' responses: '200': description: 'Success. The response body contains the organization information. ' content: application/json: schema: $ref: '#/components/schemas/Organization' '401': $ref: '#/components/responses/AuthorizationError' '404': description: 'Not found. Organization not found. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: 'The requested organization wasn''t found. ' value: code: not found message: organization not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /orgs/{orgID}/secrets: get: operationId: GetOrgsIDSecrets tags: - Security and access endpoints summary: List all secret keys for an organization parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The organization ID. responses: '200': description: A list of all secret keys content: application/json: schema: $ref: '#/components/schemas/SecretKeysResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /orgs/{orgID}/members: get: operationId: GetOrgsIDMembers tags: - Security and access endpoints summary: List all members of an organization description: "Lists all users that belong to an organization.\n\nInfluxDB [users](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members](https://docs.influxdata.com/influxdb/cloud/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](https://docs.influxdata.com/influxdb/cloud/users/)\n- [Manage members](https://docs.influxdata.com/influxdb/cloud/organizations/members/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: 'The ID of the organization to retrieve users for. ' responses: '200': description: 'Success. The response body contains a list of all users within the organization. ' content: application/json: schema: $ref: '#/components/schemas/ResourceMembers' examples: successResponse: value: links: self: /api/v2/orgs/055aa4783aa38398/members users: - role: member links: self: /api/v2/users/791df274afd48a83 id: 791df274afd48a83 name: example_user_1 status: active - role: owner links: self: /api/v2/users/09cfb87051cbe000 id: 09cfb87051cbe000 name: example_user_2 status: active '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': description: 'Not found. InfluxDB can''t find the organization. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: 'The requested organization wasn''t found. ' value: code: not found message: 404 page not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /orgs/{orgID}/members/{userID}: delete: operationId: DeleteOrgsIDMembersID tags: - 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-(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](https://docs.influxdata.com/influxdb/cloud/organizations/members/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the user to remove. - in: path name: orgID schema: type: string required: true description: The ID of the organization to remove a user from. responses: '204': description: 'Success. The user is no longer a member of the organization. ' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /orgs/{orgID}/owners: get: operationId: GetOrgsIDOwners tags: - 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-(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' - in: path name: orgID schema: type: string required: true description: 'The ID of the organization to list owners for. ' responses: '200': description: A list of organization owners content: application/json: schema: $ref: '#/components/schemas/ResourceOwners' examples: successResponse: value: links: self: /api/v2/orgs/055aa4783aa38398/owners users: - role: owner links: self: /api/v2/users/09cfb87051cbe000 id: 09cfb87051cbe000 name: example_user_2 status: active '404': description: Organization not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /orgs/{orgID}/owners/{userID}: delete: operationId: DeleteOrgsIDOwnersID tags: - Security and access endpoints summary: Remove an owner from an organization description: "Removes an [owner](https://docs.influxdata.com/influxdb/cloud/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' - in: path name: userID schema: type: string required: true description: The ID of the user to remove. - in: path name: orgID schema: type: string required: true description: 'The ID of the organization to remove an owner from. ' responses: '204': description: 'Success. The user is no longer an owner of the organization. ' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /orgs/{orgID}/secrets/delete: post: deprecated: true operationId: PostOrgsIDSecrets tags: - Security and access endpoints summary: Delete secrets from an organization parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The organization ID. requestBody: description: Secret key to delete required: true content: application/json: schema: $ref: '#/components/schemas/SecretKeys' responses: '204': description: Keys successfully patched default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /orgs/{orgID}/secrets/{secretID}: delete: operationId: DeleteOrgsIDSecretsID tags: - Security and access endpoints summary: Delete a secret from an organization parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The organization ID. - in: path name: secretID schema: type: string required: true description: The secret ID. responses: '204': description: Keys successfully deleted default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' /users/{userID}/password: post: operationId: PostUsersIDPassword tags: - Security and access endpoints summary: Update a password description: "Updates a user password.\n\n#### InfluxDB Cloud\n\n- Doesn't allow you to manage user passwords through the API.\n Use the InfluxDB Cloud user interface (UI) to update a password.\n\n#### Related guides\n\n- [InfluxDB Cloud - Change your password](https://docs.influxdata.com/influxdb/cloud/account-management/change-password/)\n- [InfluxDB OSS - Change your password](https://docs.influxdata.com/influxdb/latest/users/change-password/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the user to set the password for. requestBody: description: The new password to set for the user. required: true content: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' responses: '204': description: Success. The password is updated. '400': description: 'Bad request. #### InfluxDB Cloud - Doesn''t allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS - Doesn''t understand a value passed in the request. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: updatePasswordNotAllowed: summary: Cloud API can't update passwords value: code: invalid message: passwords cannot be changed through the InfluxDB Cloud API default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' x-codeSamples: - lang: Shell label: 'cURL: use HTTP POST to update the user password' source: "curl --request POST \\\n \"http://localhost:8086/api/v2/users/USER_ID/password\" \\\n --header 'Content-type: application/json' \\\n --header \"Authorization: Token INFLUX_TOKEN\" \\\n --data-binary @- << EOF\n {\"password\": \"NEW_USER_PASSWORD\"}\nEOF\n" put: operationId: PutUsersIDPassword tags: - Security and access endpoints summary: Update a password description: "Updates a user password.\n\nUse this endpoint to let a user authenticate with\n[Basic authentication credentials](#section/Authentication/BasicAuthentication)\nand set a new password.\n\n#### InfluxDB Cloud\n\n- Doesn't allow you to manage user passwords through the API.\n Use the InfluxDB Cloud user interface (UI) to update a password.\n\n#### Related guides\n\n- [InfluxDB Cloud - Change your password](https://docs.influxdata.com/influxdb/cloud/account-management/change-password/)\n- [InfluxDB OSS - Change your password](https://docs.influxdata.com/influxdb/latest/users/change-password/)\n" security: - BasicAuthentication: [] parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the user to set the password for. requestBody: description: The new password to set for the user. required: true content: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' responses: '204': description: Success. The password is updated. '400': description: 'Bad request. #### InfluxDB Cloud - Doesn''t allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS - Doesn''t understand a value passed in the request. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: updatePasswordNotAllowed: summary: Cloud API can't update passwords value: code: invalid message: passwords cannot be changed through the InfluxDB Cloud API default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' x-codeSamples: - lang: Shell label: 'cURL: use Basic auth to update the user password' source: "curl -c ./cookie-file.tmp --request POST \\\n \"http://localhost:8086/api/v2/signin\" \\\n --user \"${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}\"\n\ncurl -b ./cookie-file.tmp --request PUT \\\n \"http://localhost:8086/api/v2/users/USER_ID/password\" \\\n --header 'Content-type: application/json' \\\n --data-binary @- << EOF\n {\"password\": \"NEW_USER_PASSWORD\"}\nEOF\n" /authorizations: get: operationId: GetAuthorizations tags: - 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](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: - Security and access endpoints 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: - 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](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: - 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: - 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 tags: - Security and access endpoints summary: List users description: "Lists [users](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user).\n\nTo limit which users are returned, pass query parameters in your request.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't allow listing all users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions for InfluxDB Cloud\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| List all users | Operator token | InfluxData internal use only |\n| List a specific user | `read-users` or `read-user USER_ID` |\n\n*`USER_ID`* is the ID of the user that you want to retrieve.\n\n#### Related guides\n\n- [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: name schema: type: string description: 'A user name. Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). ' - in: query name: id schema: type: string description: 'A user id. Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). ' responses: '200': description: "Success. The response contains a list of `users`.\n\n#### InfluxDB Cloud\n\n- Returns an empty `users` list if you don't pass _`id`_ or _`name`_ parameters and don't use an\n _operator token_.\n Only InfluxData can access InfluxDB Cloud operator tokens.\n" content: application/json: schema: $ref: '#/components/schemas/Users' '401': description: 'Unauthorized. ' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: "Unprocessable entity.\n\nThe error may indicate one of the following problems:\n\n- The request body isn't valid--the request is well-formed,\n but InfluxDB can't process it due to semantic errors.\n- You passed a parameter combination that InfluxDB doesn't support.\n" content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' /users/{userID}: get: operationId: GetUsersID tags: - Security and access endpoints summary: Retrieve a user description: 'Retrieves a [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/latest/organizations/users/) ' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: 'A user ID. Retrieves the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). ' responses: '200': description: Success. The response body contains the user. content: application/json: schema: $ref: '#/components/schemas/UserResponse' 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 InternalServerError: description: 'Internal server error. The server encountered an unexpected situation. ' content: application/json: schema: $ref: '#/components/schemas/Error' GeneralServerError: description: Non 2XX error response from server. content: application/json: schema: $ref: '#/components/schemas/Error' ResourceNotFoundError: description: "Not found.\nA requested resource was not found.\nThe response body contains the requested resource type and the name value\n(if you passed it)--for example:\n\n- `\"organization name \\\"my-org\\\" not found\"`\n- `\"organization not found\"`: indicates you passed an ID that did not match\n an organization.\n" content: application/json: schema: $ref: '#/components/schemas/Error' examples: org-not-found: summary: Organization name not found value: code: not found message: organization name "my-org" not found bucket-not-found: summary: Bucket name not found value: code: not found message: bucket "air_sensor" not found orgID-not-found: summary: Organization ID not found value: code: not found message: organization not found BadRequestError: description: 'Bad request. The response body contains detail about the error. #### InfluxDB OSS - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: orgProvidedNotFound: summary: The org or orgID passed doesn't own the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' schemas: SecretKeysResponse: allOf: - $ref: '#/components/schemas/SecretKeys' - type: object properties: links: readOnly: true type: object properties: self: type: string org: type: string Permission: required: - action - resource properties: action: type: string enum: - read - write resource: $ref: '#/components/schemas/Resource' SecretKeys: type: object properties: secrets: type: array items: type: string 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' Link: type: string format: uri readOnly: true description: URI of 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 ResourceMember: allOf: - $ref: '#/components/schemas/UserResponse' - type: object properties: role: type: string default: member enum: - member 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. Users: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/UserResponse' ResourceOwners: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/ResourceOwner' 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' UserResponse: properties: id: readOnly: true type: string description: 'The user ID. ' name: type: string description: 'The user name. ' status: description: 'The status of a user. An inactive user can''t read or write resources. ' default: active type: string enum: - active - inactive links: type: object readOnly: true example: self: /api/v2/users/1 properties: self: type: string format: uri required: - name Organizations: type: object properties: links: $ref: '#/components/schemas/Links' orgs: type: array items: $ref: '#/components/schemas/Organization' Authorizations: type: object properties: links: readOnly: true $ref: '#/components/schemas/Links' authorizations: type: array items: $ref: '#/components/schemas/Authorization' Organization: properties: links: type: object readOnly: true example: self: /api/v2/orgs/1 members: /api/v2/orgs/1/members owners: /api/v2/orgs/1/owners labels: /api/v2/orgs/1/labels secrets: /api/v2/orgs/1/secrets buckets: /api/v2/buckets?org=myorg tasks: /api/v2/tasks?org=myorg dashboards: /api/v2/dashboards?org=myorg properties: self: $ref: '#/components/schemas/Link' members: $ref: '#/components/schemas/Link' owners: $ref: '#/components/schemas/Link' labels: $ref: '#/components/schemas/Link' secrets: $ref: '#/components/schemas/Link' buckets: $ref: '#/components/schemas/Link' tasks: $ref: '#/components/schemas/Link' dashboards: $ref: '#/components/schemas/Link' id: readOnly: true type: string name: type: string defaultStorageType: description: Discloses whether the organization uses TSM or IOx. type: string enum: - tsm - iox description: type: string createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true status: description: If inactive, the organization is inactive. default: active type: string enum: - active - inactive required: - name PasswordResetBody: properties: password: type: string required: - password 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. ' ResourceOwner: allOf: - $ref: '#/components/schemas/UserResponse' - type: object properties: role: type: string default: owner enum: - owner ResourceMembers: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/ResourceMember' 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 parameters: Limit: in: query name: limit required: false description: 'Limits the number of records returned. Default is `20`. ' schema: type: integer minimum: 1 maximum: 100 default: 20 Offset: in: query name: offset required: false description: 'The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/cloud/api/#tag/Pagination). ' schema: type: integer minimum: 0 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 Descending: in: query name: descending required: false schema: type: boolean default: false examples: 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 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 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: []