Authorizations (API tokens)

Download InfluxDB Cloud Serverless API Spec
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 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

Parameters

Query parameters
userID string
A user ID. Only returns authorizations scoped to the specified user.
user string
A user name. Only returns authorizations scoped to the specified user.
orgID string
An organization ID. Only returns authorizations that belong to the specified organization.
org string
An organization name. Only returns authorizations that belong to the specified organization.
token string

An API 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
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[]
createdAt string <date-time>
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>
URI of resource.
user string <uri>
URI of resource.
org string
The organization name. Specifies the organization that the token is scoped to.
orgID required string
The organization ID. Specifies the organization that the authorization is scoped to.
permissions required object[]
The list of permissions. An authorization must have at least one permission.
action required string
Allowed: read , write
resource required object
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 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 <date-time>
user string
The user name. Specifies the 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 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>
URI of resource.
prev string <uri>
URI of resource.
self required string <uri>
URI of resource.
400 Non 2XX error response from server.
code required string
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.
500 Internal server error. The server encountered an unexpected situation.
code required string
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.
default Non 2XX error response from server.
code required string
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.

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

Parameters

Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

The authorization to create.
Content-Type: application/json
description string
A description of the token.
orgID required string
An organization ID. Specifies the organization that owns the authorization.
permissions required object[]

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 required string
Allowed: read , write
resource required object
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 required string
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
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

201 Success. The authorization is created. The response body contains the authorization.
400 Non 2XX error response from server.
code required string
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.
500 Internal server error. The server encountered an unexpected situation.
code required string
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.
default Non 2XX error response from server.
code required string
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.

Parameters

Path parameters
authID required string
An authorization ID. Specifies the authorization to retrieve.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/authorizations/{authID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the authorization.
400 Bad request.
code required string
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.
404 Not found.
code required string
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.
500 Internal server error. The server encountered an unexpected situation.
code required string
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.
default Non 2XX error response from server.
code required string
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 required string
An authorization ID. Specifies the authorization to update.
Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

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
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

200 Success. The response body contains the updated authorization.
default Non 2XX error response from server.
code required string
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 required string
An authorization ID. Specifies the authorization to delete.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request DELETE \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/authorizations/{authID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The authorization is deleted.
400 Bad request.
code required string
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.
404 Not found.
code required string
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.
500 Internal server error. The server encountered an unexpected situation.
code required string
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.
default Non 2XX error response from server.
code required string
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.

Was this page helpful?

Thank you for your feedback!