Security and access endpoints

Download InfluxDB Cloud (TSM) API Spec
Endpoints for managing authentication and access control in InfluxDB Cloud.
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 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.

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
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 values in clear text.
  • If the request uses an operator token, InfluxDB OSS returns authorizations for all organizations in the instance.
authorizations object[]
links string
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
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"

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.

InfluxDB OSS v2

  • InfluxDB OSS returns API token values in authorizations.
  • If the request uses an operator token, InfluxDB OSS returns authorizations for all organizations in the instance.

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.
GET /api/v2/orgs

List organizations

Lists organizations.

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.

Parameters

Query parameters
offset integer

The offset for pagination. The number of records to skip.

For more information about pagination parameters, see Pagination.

limit integer
Limits the number of records returned. Default is 20.
Default: 20
descending boolean
org string
An organization name. Only returns the specified organization.
orgID string
An organization ID. Only returns the specified organization.
userID string
A user ID. Only returns organizations where the specified user is a member or owner.
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/orgs" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains a list of organizations.
links string
orgs object[]
400

Bad request. The response body contains detail about the error.

InfluxDB OSS v2

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.
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. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example:

  • "organization name \"my-org\" not found"
  • "organization not found": indicates you passed an ID that did not match an organization.
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.
GET /api/v2/orgs/{orgID}

Retrieve an organization

Retrieves an organization.

Use this endpoint to retrieve information for a specific organization.

Parameters

Path parameters
orgID required string
The ID of the organization 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/orgs/{orgID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the organization information.
createdAt string <date-time>
defaultStorageType string
Discloses whether the organization uses TSM or IOx.
Allowed: tsm , iox
description string
id string
links object
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"}
buckets string
dashboards string
labels string
members string
owners string
secrets string
self string
tasks string
name required string
status string
If inactive, the organization is inactive.
Allowed: active , inactive
Default: active
updatedAt string <date-time>
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. Organization 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 Unexpected error
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/orgs/{orgID}/members

List all members of an organization

Lists all users that belong to an organization.

InfluxDB users have permission to access InfluxDB.

Members are users within the organization.

InfluxDB Cloud

Limitations

  • Member permissions are separate from API token permissions.
  • Member permissions are used in the context of the InfluxDB UI.

Required permissions

  • read-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to retrieve members for.

Parameters

Path parameters
orgID required string
The ID of the organization to retrieve users for.
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/orgs/{orgID}/members" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains a list of all users within the organization.
links object
self string <uri>
users object[]
400

Bad request. The response body contains detail about the error.

InfluxDB OSS v2

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.
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. InfluxDB can’t find the organization.
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 Unexpected error
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/orgs/{orgID}/members/{userID}

Remove a member from an organization

Removes a member from an organization.

Use this endpoint to remove a user’s member privileges for an organization. Removing member privileges removes the user’s read and write permissions from the organization.

InfluxDB Cloud

Limitations

  • Member permissions are separate from API token permissions.
  • Member permissions are used in the context of the InfluxDB UI.

Required permissions

  • write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to remove an owner from.

Parameters

Path parameters
userID required string
The ID of the user to remove.
orgID required string
The ID of the organization to remove a user from.
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/orgs/{orgID}/members/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The user is no longer a member of the organization.
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. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example:

  • "organization name \"my-org\" not found"
  • "organization not found": indicates you passed an ID that did not match an organization.
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 Unexpected error
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/orgs/{orgID}/owners

List all owners of an organization

Lists all owners of an organization.

InfluxDB Cloud

Required permissions

  • read-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to retrieve a list of owners from.

Parameters

Path parameters
orgID required string
The ID of the organization to list owners for.
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/orgs/{orgID}/owners" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 A list of organization owners
links object
self string <uri>
users object[]
404 Organization 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.
default Unexpected error
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/orgs/{orgID}/owners/{userID}

Remove an owner from an organization

Removes an owner from the organization.

Organization owners have permission to delete organizations and remove user and member permissions from the organization.

InfluxDB Cloud

Limitations

  • Owner permissions are separate from API token permissions.
  • Owner permissions are used in the context of the InfluxDB UI.

Required permissions

  • write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to remove an owner from.

Parameters

Path parameters
userID required string
The ID of the user to remove.
orgID required string
The ID of the organization to remove an owner from.
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/orgs/{orgID}/owners/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The user is no longer an owner of the organization.
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. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example:

  • "organization name \"my-org\" not found"
  • "organization not found": indicates you passed an ID that did not match an organization.
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 Unexpected error
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/orgs/{orgID}/secrets

List all secret keys for an organization

Parameters

Path parameters
orgID required string
The organization ID.
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/orgs/{orgID}/secrets" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 A list of all secret keys
default Unexpected error
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/orgs/{orgID}/secrets/{secretID}

Delete a secret from an organization

Parameters

Path parameters
orgID required string
The organization ID.
secretID required string
The secret ID.
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/orgs/{orgID}/secrets/{secretID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Keys successfully deleted
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/orgs/{orgID}/secrets/delete

Delete secrets from an organization

Parameters

Path parameters
orgID required string
The organization ID.
Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

Secret key to delete
Content-Type: application/json
secrets string[]
Example request Ask AI about this
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/orgs/{orgID}/secrets/delete" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "secrets": [
    "example"
  ]
}'

Responses

204 Keys successfully patched
default Unexpected error
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/signin

Create a user session.

Authenticates Basic authentication credentials for a user, and then, if successful, generates a user session.

To authenticate a user, pass the HTTP Authorization header with the Basic scheme and the base64-encoded username and password. For syntax and more information, see Basic Authentication for syntax and more information.

If authentication is successful, InfluxDB creates a new session for the user and then returns the session cookie in the Set-Cookie response header.

InfluxDB stores user sessions in memory only. They expire within ten minutes and during restarts of the InfluxDB instance.

User sessions with authorizations

  • In InfluxDB Cloud, a user session inherits all the user’s permissions for the organization.
  • In InfluxDB OSS, a user session inherits all the user’s permissions for all the organizations that the user belongs to.

Parameters

Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/signin" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The user is authenticated. The Set-Cookie response header contains the session cookie.
401

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.
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.
403 Forbidden. The user account is disabled.
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 Unsuccessful authentication.
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/signout

Expire a user session

Expires a user session specified by a session cookie.

Use this endpoint to expire a user session that was generated when the user authenticated with the InfluxDB Developer Console (UI) or the POST /api/v2/signin endpoint.

For example, the POST /api/v2/signout endpoint represents the third step in the following three-step process to authenticate a user, retrieve the user resource, and then expire the session:

  1. Send a request with the user’s Basic authentication credentials to the POST /api/v2/signin endpoint to create a user session and generate a session cookie.
  2. Send a request to the GET /api/v2/me endpoint, passing the stored session cookie from step 1 to retrieve user information.
  3. Send a request to the POST /api/v2/signout endpoint, passing the stored session cookie to expire the session.

See the complete example in request samples.

InfluxDB stores user sessions in memory only. If a user doesn’t sign out, then the user session automatically expires within ten minutes or during a restart of the InfluxDB instance.

To learn more about cookies in HTTP requests, see Mozilla Developer Network (MDN) Web Docs, HTTP cookies.

Parameters

Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/signout" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The session is expired.
401 Unauthorized.
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 The session expiry is unsuccessful.
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/users

List users

Lists users.

To limit which users are returned, pass query parameters in your request.

InfluxDB Cloud

  • InfluxDB Cloud doesn’t allow listing all users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information.

Required permissions for InfluxDB Cloud

ActionPermission requiredRestriction
List all usersOperator tokenInfluxData internal use only
List a specific userread-users or read-user USER_ID

USER_ID is the ID of the user that you want to retrieve.

Parameters

Query parameters
name string
A user name. Only lists the specified user.
id string
A user id. Only lists the specified user.
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/users" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200

Success. The response contains a list of users.

InfluxDB Cloud

  • Returns an empty users list if you don’t pass id or name parameters and don’t use an operator token. Only InfluxData can access InfluxDB Cloud operator tokens.
links object
self string <uri>
users object[]
401 Unauthorized.
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.
422

Unprocessable entity.

The error may indicate one of the following problems:

  • The request body isn’t valid–the request is well-formed, but InfluxDB can’t process it due to semantic errors.
  • You passed a parameter combination that InfluxDB doesn’t support.
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.
POST /api/v2/users/{userID}/password

Update a password

Updates a user password.

InfluxDB Cloud

  • Doesn’t allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password.

Parameters

Path parameters
userID required string
The ID of the user to set the password for.
Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

The new password to set for the user.
Content-Type: application/json
password required string
Example request Ask AI about this
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/users/{userID}/password" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "password": "PASSWORD"
}'

Responses

204 Success. The password is updated.
400

Bad request.

InfluxDB Cloud

  • Doesn’t allow you to manage passwords through the API; always responds with this status.

InfluxDB OSS v2

  • Doesn’t understand a value passed in the 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.
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.
PUT /api/v2/users/{userID}/password

Update a password

Updates a user password.

Use this endpoint to let a user authenticate with Basic authentication credentials and set a new password.

InfluxDB Cloud

  • Doesn’t allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password.

Parameters

Path parameters
userID required string
The ID of the user to set the password for.
Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

The new password to set for the user.
Content-Type: application/json
password required string
Example request Ask AI about this
curl --request PUT \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/users/{userID}/password" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "password": "PASSWORD"
}'

Responses

204 Success. The password is updated.
400

Bad request.

InfluxDB Cloud

  • Doesn’t allow you to manage passwords through the API; always responds with this status.

InfluxDB OSS v2

  • Doesn’t understand a value passed in the 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.
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!