--- title: Authorizations (API tokens) description: Create and manage API token authorizations that grant read and write permissions to InfluxDB Cloud organization resources. url: https://docs.influxdata.com/influxdb/cloud/api/authorizations-api-tokens/ estimated_tokens: 4699 product: InfluxDB Cloud (TSM) version: cloud publisher: InfluxData canonical: https://docs.influxdata.com/influxdb/cloud/api/authorizations-api-tokens/ --- [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage API token authorizations that grant read and write permissions to InfluxDB Cloud organization resources. GET`/api/v2/authorizations` ### List authorizations Lists authorizations. To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations. #### InfluxDB Cloud * InfluxDB Cloud doesn’t expose [API token](/influxdb/cloud/reference/glossary/#token)values in `GET /api/v2/authorizations` responses; returns `token: redacted` for all authorizations. #### Required permissions To retrieve an authorization, the request must use an API token that has the following permissions: * `read-authorizations` * `read-user` for the user that the authorization is scoped to #### Related guides * [View tokens](/influxdb/cloud/security/tokens/view-tokens/) #### Parameters ##### Query parameters `userID`string A user ID. Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). `user`string A user name. Only returns authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). `orgID`string An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). `org`string An organization name. Only returns authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). `token`string An API [token](/influxdb/cloud/reference/glossary/#token) value. Specifies an authorization by its `token` property value and returns the authorization. #### InfluxDB OSS v2 * Doesn’t support this parameter. InfluxDB OSS ignores the `token=` parameter, applies other parameters, and then returns the result. #### Limitations * The parameter is non-repeatable. If you specify more than one, only the first one is used. If a resource with the specified property value doesn’t exist, then the response body contains an empty list. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains a list of authorizations. If the response body is missing authorizations that you expect, check that the API token used in the request has `read-user` permission for the users (`userID` property value) in those authorizations. #### InfluxDB OSS v2 * **Warning**: The response body contains authorizations with their[API token](/influxdb/cloud/reference/glossary/#token) values in clear text. * If the request uses an *[operator token](/influxdb/v2/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. `authorizations`object[] `links`string 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/authorizations` ### Create an authorization Creates an authorization and returns the authorization with the generated API [token](/influxdb/cloud/reference/glossary/#token). Use this endpoint to create an authorization, which generates an API token with permissions to `read` or `write` to a specific resource or `type` of resource. The API token is the authorization’s `token` property value. To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens. * InfluxDB allows access to the API token value immediately after the authorization is created. * You can’t change access (read/write) permissions for an API token after it’s created. * Tokens stop working when the user who created the token is deleted. 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. #### Required permissions * `write-authorizations` * `write-user` for the user that the authorization is scoped to #### Related guides * [Create a token](/influxdb/cloud/security/tokens/create-token/) #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired The authorization to create. Content-Type:`application/json` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/authorizations" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" ``` #### Responses 201Success. The authorization is created. The response body contains the authorization. 400Non 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. GET`/api/v2/authorizations/{authID}` ### Retrieve an authorization Retrieves an authorization. Use this endpoint to retrieve information about an API token, including the token’s permissions and the user that the token is scoped to. #### InfluxDB OSS v2 * InfluxDB OSS returns[API token](/influxdb/cloud/reference/glossary/#token) values in authorizations. * If the request uses an *[operator token](/influxdb/v2/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. #### Related guides * [View tokens](/influxdb/cloud/security/tokens/view-tokens/) #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to retrieve. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The response body contains the authorization. 400Bad request. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. PATCH`/api/v2/authorizations/{authID}` ### Update an API token to be active or inactive 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. #### Parameters ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to update. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired In the request body, provide the authorization properties to update. Content-Type:`application/json` `description`string A description of the token. `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "description": "DESCRIPTION", "status": "active" }' ``` #### Responses 200Success. The response body contains the updated authorization. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. DELETE`/api/v2/authorizations/{authID}` ### Delete an authorization 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 ##### Path parameters `authID`requiredstring An authorization ID. Specifies the authorization to delete. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/authorizations/{authID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204Success. The authorization is deleted. 400Bad request. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: * The `Authorization: Token` header is missing or malformed. * The API token value is missing from the header. * The token doesn’t have sufficient permissions to write to this organization and bucket. `code`string The HTTP status code description. Default is `unauthorized`. Allowed:`unauthorized` `message`string A human-readable message that may contain detail about the error. 404Not found. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. #### Related * [Manage API tokens](/influxdb/cloud/security/tokens/) * [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/)