Users

Download InfluxDB API Spec
Create and manage users that have access to InfluxDB OSS v2 organizations and resources.
GET /api/v2/me

Retrieve the currently authenticated user

Parameters

Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request GET \
  "http://localhost:8086/api/v2/me" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the currently authenticated user.
id string
The user ID.
links object
Example: {"self":"/api/v2/users/1"}
self string <uri>
name required string
The user name.
status string
The status of a user. An inactive user can’t read or write resources.
Allowed: active , inactive
Default: active
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.
PUT /api/v2/me/password

Update a password

Updates the password for the signed-in user.

This endpoint represents the third step in the following three-step process to let a user with a user session update their password:

  1. Pass the user’s Basic authentication credentials to the POST /api/v2/signin endpoint to create a user session and generate a session cookie.
  2. From the response in the first step, extract the session cookie (Set-Cookie) header.
  3. Pass the following in a request to the PUT /api/v2/me/password endpoint:
    • The Set-Cookie header from the second step
    • The Authorization Basic header with the user’s Basic authentication credentials
    • {"password": "NEW_PASSWORD"} in the request body

InfluxDB Cloud

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

Parameters

Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

The new password.
Content-Type: application/json
password required string
Example request Ask AI about this
curl --request PUT \
  "http://localhost:8086/api/v2/me/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 let you manage user passwords through the API; always responds with this status.

InfluxDB OSS v2

  • Doesn’t understand a value passed in the request.
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.
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.
GET /api/v2/users

List users

Lists users. Default limit is 20.

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

Required permissions for InfluxDB OSS

ActionPermission requiredRestriction
List all usersOperator token
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
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
after string

A resource ID to seek from. Returns records created after the specified record; results don’t include the specified record.

Use after instead of the offset parameter. For more information about pagination parameters, see Pagination.

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 \
  "http://localhost:8086/api/v2/users" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response contains a list of users.
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

Create a user

Creates a user that can access InfluxDB. Returns the user.

Use this endpoint to create a user that can sign in to start a user session through one of the following interfaces:

  • InfluxDB UI
  • /api/v2/signin InfluxDB API endpoint
  • InfluxDB CLI

This endpoint represents the first two steps in a four-step process to allow a user to authenticate with a username and password, and then access data in an organization:

  1. Create a user: send a POST request to POST /api/v2/users. The name property is required.
  2. Extract the user ID (id property) value from the API response for step 1.
  3. Create an authorization (and API token) for the user: send a POST request to POST /api/v2/authorizations, passing the user ID (id) from step 2.
  4. Create a password for the user: send a POST request to POST /api/v2/users/USER_ID/password, passing the user ID from step 2.

Required permissions

ActionPermission requiredRestriction
Create a userOperator token

Parameters

Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

The user to create.
Content-Type: application/json
id string
The user ID.
name required string
The user name.
status string
If inactive, the user is inactive. Default is active.
Allowed: active , inactive
Default: active
Example request Ask AI about this
curl --request POST \
  "http://localhost:8086/api/v2/users" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "id": "ID",
  "name": "NAME",
  "status": "active"
}'

Responses

201 Success. The response body contains the user.
id string
The user ID.
links object
Example: {"self":"/api/v2/users/1"}
self string <uri>
name required string
The user name.
status string
The status of a user. An inactive user can’t read or write resources.
Allowed: active , inactive
Default: active
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.
GET /api/v2/users/{userID}

Retrieve a user

Retrieves a user.

Parameters

Path parameters
userID required string
A user ID. Retrieves the specified user.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request GET \
  "http://localhost:8086/api/v2/users/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the user.
id string
The user ID.
links object
Example: {"self":"/api/v2/users/1"}
self string <uri>
name required string
The user name.
status string
The status of a user. An inactive user can’t read or write resources.
Allowed: active , inactive
Default: active
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/users/{userID}

Update a user

Updates a user and returns the user.

Required permissions

ActionPermission required
Update a userwrite-users or write-user USER_ID

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

Parameters

Path parameters
userID required string
A user ID. Specifies the user to update.
Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

In the request body, provide the user properties to update.
Content-Type: application/json
id string
The user ID.
name required string
The user name.
status string
If inactive, the user is inactive. Default is active.
Allowed: active , inactive
Default: active
Example request Ask AI about this
curl --request PATCH \
  "http://localhost:8086/api/v2/users/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "id": "ID",
  "name": "NAME",
  "status": "active"
}'

Responses

200 Success. The response body contains the user.
id string
The user ID.
links object
Example: {"self":"/api/v2/users/1"}
self string <uri>
name required string
The user name.
status string
The status of a user. An inactive user can’t read or write resources.
Allowed: active , inactive
Default: active
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.
DELETE /api/v2/users/{userID}

Delete a user

Deletes a user.

Required permissions

ActionPermission required
Delete a userwrite-users or write-user USER_ID

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

Parameters

Path parameters
userID required string
A user ID. Specifies the user to delete.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request DELETE \
  "http://localhost:8086/api/v2/users/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The user is deleted.
400 Bad request. The response body contains detail about the 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.
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/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 \
  "http://localhost:8086/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 \
  "http://localhost:8086/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!