--- 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: 5642 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 * 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 * **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/cloud/security/tokens/#operator-token)*, InfluxDB OSS returns authorizations for all organizations in the instance. `authorizations`object[] `createdAt`string \ `description`string A description of the token. `id`string The authorization ID. `links`object Example:`{"self":"/api/v2/authorizations/1","user":"/api/v2/users/12"}` `self`string \ URI of resource. `user`string \ URI of resource. `org`string The organization name. Specifies the [organization](/influxdb/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/reference/glossary/#organization) that the authorization is scoped to. `permissions`requiredobject[] The list of permissions. An authorization must have at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The API token. The token value is unique to the authorization.[API tokens](/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). `updatedAt`string \ `user`string The user name. Specifies the [user](/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. `userID`string The user ID. Specifies the [user](/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. `links`object URI pointers for additional paged results. `next`string \ URI of resource. `prev`string \ URI of resource. `self`requiredstring \ URI of resource. 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` `description`string A description of the token. `orgID`requiredstring An organization ID. Specifies the organization that owns the authorization. `permissions`requiredobject[] 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. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `id`string A resource ID. Identifies a specific resource. `name`string The name of the resource.*Note: not all resource types have a `name` property*. `org`string An organization name. The organization that owns the resource. `orgID`string An organization ID. Identifies the organization that owns the resource. `type`requiredstring A resource type. Identifies the API resource’s type (or *kind*). Allowed:`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` `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `userID`string 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. 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" \ --data-raw '{ "description": "DESCRIPTION", "orgID": "ORGID", "permissions": [ { "action": "read", "resource": {} } ], "status": "active", "userID": "USERID" }' ``` #### 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 * InfluxDB OSS returns[API token](/influxdb/cloud/reference/glossary/#token) values in authorizations. * If the request uses an *[operator token](/influxdb/cloud/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](/influxdb/cloud/security/tokens/view-tokens/)