--- title: Authorizations (API tokens) description: Create and manage API token authorizations that grant read and write permissions to InfluxDB 3 Cloud Serverless organization resources. url: https://docs.influxdata.com/influxdb3/cloud-serverless/api/authorizations-api-tokens/ estimated_tokens: 4531 product: InfluxDB 3 Cloud version: cloud publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/cloud-serverless/api/authorizations-api-tokens/ --- [Download InfluxDB Cloud Serverless API Spec](/openapi/influxdb-cloud-serverless-api.yml) Create and manage API token authorizations that grant read and write permissions to InfluxDB 3 Cloud Serverless 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 3 Cloud Serverless doesn’t expose [API token](/influxdb3/cloud-serverless/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](/influxdb3/cloud-serverless/security/tokens/view-tokens/) #### Parameters ##### Query parameters `userID`string A user ID. Only returns authorizations scoped to the specified [user](/influxdb3/cloud-serverless/reference/glossary/#user). `user`string A user name. Only returns authorizations scoped to the specified [user](/influxdb3/cloud-serverless/reference/glossary/#user). `orgID`string An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb3/cloud-serverless/reference/glossary/#organization). `org`string An organization name. Only returns authorizations that belong to the specified [organization](/influxdb3/cloud-serverless/reference/glossary/#organization). `token`string An API [token](/influxdb3/cloud-serverless/reference/glossary/#token) value. Specifies an authorization by its `token` property value and returns the authorization. #### 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. `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](/influxdb3/cloud-serverless/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](/influxdb3/cloud-serverless/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. #### Related guides * [View tokens](/influxdb3/cloud-serverless/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`. #### 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](/influxdb3/cloud-serverless/security/tokens/) * [InfluxDB 3 API client libraries](/influxdb3/cloud-serverless/reference/client-libraries/v3/)