openapi: 3.0.0 info: title: Complete InfluxDB Cloud Authorizations (API tokens) Authorizations (API tokens) Security and access endpoints 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: - name: Security and access endpoints 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: - Security and access endpoints 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: - Security and access endpoints /api/v2/authorizations/{authID}: delete: description: 'Deletes an authorization. Use the endpoint to delete an API token. If you want to disable an API token instead of delete it, [update the authorization''s status to `inactive`](#operation/PatchAuthorizationsID). ' operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - description: 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: - Security and access endpoints 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: - Security and access endpoints patch: description: 'Updates an authorization. Use this endpoint to set an API token''s status to be _active_ or _inactive_. InfluxDB rejects requests that use inactive API tokens. ' operationId: PatchAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - description: 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: - Security and access endpoints /api/v2/orgs: get: 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/) ' operationId: GetOrgs parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Descending' - description: 'An organization name. Only returns the specified organization. ' in: query name: org schema: type: string - description: 'An organization ID. Only returns the specified organization. ' in: query name: orgID schema: type: string - description: 'A user ID. Only returns organizations where the specified user is a member or owner. ' in: query name: userID schema: type: string responses: '200': content: application/json: examples: successResponse: value: links: self: /api/v2/orgs orgs: - createdAt: '2022-07-17T23:00:30.778487Z' description: Example InfluxDB organization id: INFLUX_ORG_ID 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 name: INFLUX_ORG updatedAt: '2022-07-17T23:00:30.778487Z' schema: $ref: '#/components/schemas/Organizations' description: Success. The response body contains a list of organizations. '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' summary: List organizations tags: - Security and access endpoints /api/v2/orgs/{orgID}: get: 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/) ' operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' - description: 'The ID of the organization to retrieve. ' in: path name: orgID required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Organization' description: 'Success. The response body contains the organization information. ' '401': $ref: '#/components/responses/AuthorizationError' '404': content: application/json: examples: notFound: summary: 'The requested organization wasn''t found. ' value: code: not found message: organization not found schema: $ref: '#/components/schemas/Error' description: 'Not found. Organization not found. ' '500': $ref: '#/components/responses/InternalServerError' default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error summary: Retrieve an organization tags: - Security and access endpoints /api/v2/orgs/{orgID}/members: get: 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" operationId: GetOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - description: 'The ID of the organization to retrieve users for. ' in: path name: orgID required: true schema: type: string responses: '200': content: application/json: examples: successResponse: value: links: self: /api/v2/orgs/055aa4783aa38398/members users: - id: 791df274afd48a83 links: self: /api/v2/users/791df274afd48a83 name: example_user_1 role: member status: active - id: 09cfb87051cbe000 links: self: /api/v2/users/09cfb87051cbe000 name: example_user_2 role: owner status: active schema: $ref: '#/components/schemas/ResourceMembers' description: 'Success. The response body contains a list of all users within the organization. ' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': content: application/json: examples: notFound: summary: 'The requested organization wasn''t found. ' value: code: not found message: 404 page not found schema: $ref: '#/components/schemas/Error' description: 'Not found. InfluxDB can''t find the organization. ' '500': $ref: '#/components/responses/InternalServerError' default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error summary: List all members of an organization tags: - Security and access endpoints /api/v2/orgs/{orgID}/members/{userID}: delete: 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" operationId: DeleteOrgsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: The ID of the user to remove. in: path name: userID required: true schema: type: string - description: The ID of the organization to remove a user from. in: path name: orgID required: true schema: type: string 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: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error summary: Remove a member from an organization tags: - Security and access endpoints /api/v2/orgs/{orgID}/owners: get: 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" operationId: GetOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - description: 'The ID of the organization to list owners for. ' in: path name: orgID required: true schema: type: string responses: '200': content: application/json: examples: successResponse: value: links: self: /api/v2/orgs/055aa4783aa38398/owners users: - id: 09cfb87051cbe000 links: self: /api/v2/users/09cfb87051cbe000 name: example_user_2 role: owner status: active schema: $ref: '#/components/schemas/ResourceOwners' description: A list of organization owners '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Organization not found default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error summary: List all owners of an organization tags: - Security and access endpoints /api/v2/orgs/{orgID}/owners/{userID}: delete: 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" operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - description: The ID of the user to remove. in: path name: userID required: true schema: type: string - description: 'The ID of the organization to remove an owner from. ' in: path name: orgID required: true schema: type: string 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: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error summary: Remove an owner from an organization tags: - Security and access endpoints /api/v2/orgs/{orgID}/secrets: get: operationId: GetOrgsIDSecrets parameters: - $ref: '#/components/parameters/TraceSpan' - description: The organization ID. in: path name: orgID required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SecretKeysResponse' description: A list of all secret keys default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error summary: List all secret keys for an organization tags: - Security and access endpoints /api/v2/orgs/{orgID}/secrets/{secretID}: delete: operationId: DeleteOrgsIDSecretsID parameters: - $ref: '#/components/parameters/TraceSpan' - description: The organization ID. in: path name: orgID required: true schema: type: string - description: The secret ID. in: path name: secretID required: true schema: type: string responses: '204': description: Keys successfully deleted default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete a secret from an organization tags: - Security and access endpoints /api/v2/orgs/{orgID}/secrets/delete: post: deprecated: true operationId: PostOrgsIDSecrets parameters: - $ref: '#/components/parameters/TraceSpan' - description: The organization ID. in: path name: orgID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SecretKeys' description: Secret key to delete required: true responses: '204': description: Keys successfully patched default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error summary: Delete secrets from an organization tags: - Security and access endpoints /api/v2/signin: post: 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" operationId: PostSignin parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': description: 'Success. The user is authenticated. The `Set-Cookie` response header contains the session cookie. ' '401': content: application/json: schema: $ref: '#/components/schemas/Error' 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. ' '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden. The user account is disabled. default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unsuccessful authentication. security: - BasicAuthentication: [] summary: Create a user session. tags: - Security and access endpoints x-codeSamples: - label: 'cURL: signin with --user option encoding' lang: Shell source: "curl --request POST http://localhost:8086/api/v2/signin \\\n --user \"USERNAME:PASSWORD\"\n" /api/v2/signout: post: 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" operationId: PostSignout parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': description: Success. The session is expired. '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized. default: content: application/json: schema: $ref: '#/components/schemas/Error' description: The session expiry is unsuccessful. summary: Expire a user session tags: - Security and access endpoints x-codeSamples: - label: 'cURL: sign in a user, verify the user session, and then end the session' lang: Shell 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" /api/v2/users: get: 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" operationId: GetUsers parameters: - $ref: '#/components/parameters/TraceSpan' - description: 'A user name. Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). ' in: query name: name schema: type: string - description: 'A user id. Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). ' in: query name: id schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Users' 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" '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: 'Unauthorized. ' '422': content: application/json: schema: $ref: '#/components/schemas/Error' 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" '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: List users tags: - Security and access endpoints /api/v2/users/{userID}/password: post: 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" operationId: PostUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' - description: The ID of the user to set the password for. in: path name: userID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' description: The new password to set for the user. required: true responses: '204': description: Success. The password is updated. '400': content: application/json: examples: updatePasswordNotAllowed: summary: Cloud API can't update passwords value: code: invalid message: passwords cannot be changed through the InfluxDB Cloud API schema: $ref: '#/components/schemas/Error' 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. ' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Update a password tags: - Security and access endpoints x-codeSamples: - label: 'cURL: use HTTP POST to update the user password' lang: Shell 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: 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" operationId: PutUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' - description: The ID of the user to set the password for. in: path name: userID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' description: The new password to set for the user. required: true responses: '204': description: Success. The password is updated. '400': content: application/json: examples: updatePasswordNotAllowed: summary: Cloud API can't update passwords value: code: invalid message: passwords cannot be changed through the InfluxDB Cloud API schema: $ref: '#/components/schemas/Error' 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. ' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error security: - BasicAuthentication: [] summary: Update a password tags: - Security and access endpoints x-codeSamples: - label: 'cURL: use Basic auth to update the user password' lang: Shell 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" components: parameters: Offset: 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). ' in: query name: offset required: false schema: minimum: 0 type: integer Limit: description: 'Limits the number of records returned. Default is `20`. ' in: query name: limit required: false schema: default: 20 maximum: 100 minimum: 1 type: integer 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 Descending: in: query name: descending required: false schema: default: false type: boolean responses: GeneralServerError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Non 2XX error response from server. 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" BadRequestError: content: application/json: 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' schema: $ref: '#/components/schemas/Error' 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. ' InternalServerError: content: application/json: schema: $ref: '#/components/schemas/Error' description: 'Internal server error. The server encountered an unexpected situation. ' ResourceNotFoundError: content: application/json: examples: bucket-not-found: summary: Bucket name not found value: code: not found message: bucket "air_sensor" not found org-not-found: summary: Organization name not found value: code: not found message: organization name "my-org" not found orgID-not-found: summary: Organization ID not found value: code: not found message: organization not found schema: $ref: '#/components/schemas/Error' 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" 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 Link: description: URI of resource. format: uri readOnly: true type: string Users: properties: links: properties: self: format: uri type: string type: object users: items: $ref: '#/components/schemas/UserResponse' type: array 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 ResourceOwner: allOf: - $ref: '#/components/schemas/UserResponse' - properties: role: default: owner enum: - owner type: string type: object ResourceMembers: properties: links: properties: self: format: uri type: string type: object users: items: $ref: '#/components/schemas/ResourceMember' type: array type: object UserResponse: properties: id: description: 'The user ID. ' readOnly: true type: string links: example: self: /api/v2/users/1 properties: self: format: uri type: string readOnly: true type: object name: description: 'The user name. ' type: string status: default: active description: 'The status of a user. An inactive user can''t read or write resources. ' enum: - active - inactive type: string required: - name SecretKeysResponse: allOf: - $ref: '#/components/schemas/SecretKeys' - properties: links: properties: org: type: string self: type: string readOnly: true type: object type: object Authorizations: properties: authorizations: items: $ref: '#/components/schemas/Authorization' type: array links: $ref: '#/components/schemas/Links' readOnly: true type: object SecretKeys: properties: secrets: items: type: string type: array type: object 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 ResourceMember: allOf: - $ref: '#/components/schemas/UserResponse' - properties: role: default: member enum: - member type: string type: object 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 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 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 Organizations: properties: links: $ref: '#/components/schemas/Links' orgs: items: $ref: '#/components/schemas/Organization' type: array type: object ResourceOwners: properties: links: properties: self: format: uri type: string type: object users: items: $ref: '#/components/schemas/ResourceOwner' type: array type: object PasswordResetBody: properties: password: type: string required: - password Organization: properties: createdAt: format: date-time readOnly: true type: string defaultStorageType: description: Discloses whether the organization uses TSM or IOx. enum: - tsm - iox type: string description: type: string id: readOnly: true type: string links: example: buckets: /api/v2/buckets?org=myorg dashboards: /api/v2/dashboards?org=myorg labels: /api/v2/orgs/1/labels members: /api/v2/orgs/1/members owners: /api/v2/orgs/1/owners secrets: /api/v2/orgs/1/secrets self: /api/v2/orgs/1 tasks: /api/v2/tasks?org=myorg properties: buckets: $ref: '#/components/schemas/Link' dashboards: $ref: '#/components/schemas/Link' labels: $ref: '#/components/schemas/Link' members: $ref: '#/components/schemas/Link' owners: $ref: '#/components/schemas/Link' secrets: $ref: '#/components/schemas/Link' self: $ref: '#/components/schemas/Link' tasks: $ref: '#/components/schemas/Link' readOnly: true type: object name: type: string status: default: active description: If inactive, the organization is inactive. enum: - active - inactive type: string updatedAt: format: date-time readOnly: true type: string required: - name examples: 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 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 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: []