User management

Download InfluxDB 3 Enterprise API Spec

Manage users and their role assignments, and look up users and roles.

These endpoints are only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by starting the server with --without-user-auth false.

GET /api/v3/roles_by_name/{roleName}

Get a role by name

Returns the role with the specified name.

Requires a token or user with permission to read roles.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
roleName required string
The name of the role to retrieve.
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/roles_by_name/{roleName}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the matching role.
createdAt required integer <int64>
The Unix timestamp (seconds) when the role was created.
description string
The role description.
id required integer <int64>
The numeric ID of the role.
isRequiredRole required boolean
Whether the role is a required role.
name required string
The role name.
updatedAt required integer <int64>
The Unix timestamp (seconds) when the role was last updated.
Example request body
{
  "createdAt": 1717000000,
  "id": 1,
  "isRequiredRole": false,
  "name": "read-write",
  "updatedAt": 1717000000
}
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No role exists with the specified name.
data object
error string
GET /api/v3/roles/{id}/permissions

Get a role's permissions

Returns the permissions granted to the role with the specified ID.

Requires a token or user with permission to read roles.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
id required integer <int64>
The ID of the role.
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/roles/{id}/permissions" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the role’s permissions.
permissions required object[]
The permissions granted to the role.
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No role exists with the specified ID.
data object
error string
GET /api/v3/users_by_oauth_id/{oauth_id}

Get a user by OAuth identity-provider ID

Returns the user associated with the specified OAuth identity-provider ID. Requires the server to be configured with an OAuth validator.

Requires a token or user with permission to read users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
oauth_id required string
The OAuth identity-provider ID of the user.
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/users_by_oauth_id/{oauth_id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the matching user.
createdAt required integer <int64>
The Unix timestamp (seconds) when the user was created.
deletedAt integer <int64>
The Unix timestamp (seconds) when the user was deleted. Present only for deleted users.
displayName string
The user’s display name.
oauthId string
The user’s OAuth identity-provider ID. Present when the user has an OAuth login identity.
operatorToken string
The operator token. Returned only when creating the initial user.
requiresPasswordReset boolean
Whether the user must reset their password on next login. Present when the user has a username and password login identity.
updatedAt required integer <int64>
The Unix timestamp (seconds) when the user was last updated.
userId required integer <int64>
The numeric ID of the user.
username string
The user’s username. Present when the user has a username and password login identity.
Example request body
{
  "createdAt": 1717000000,
  "displayName": "Jane Smith",
  "requiresPasswordReset": false,
  "updatedAt": 1717000000,
  "userId": 1,
  "username": "jsmith"
}
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No user matches the specified OAuth ID, or OAuth is not configured on the server.
data object
error string
PATCH /api/v3/users/{id}

Update a user's information

Updates a user’s profile information. Currently, only the user’s display name can be updated.

Requires a token or user with permission to update users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
id required integer <int64>
The numeric ID of the user to update.

Request body required

Content-Type: application/json
displayName string
The user’s new display name.
Example request body
{
  "displayName": "Jane Smith"
}
Example request Ask AI about this
curl --request PATCH \
  "https://localhost:8181/api/v3/users/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"displayName":"Jane Smith"}'

Responses

200 Success. Returns the updated user.
createdAt required integer <int64>
The Unix timestamp (seconds) when the user was created.
deletedAt integer <int64>
The Unix timestamp (seconds) when the user was deleted. Present only for deleted users.
displayName string
The user’s display name.
oauthId string
The user’s OAuth identity-provider ID. Present when the user has an OAuth login identity.
operatorToken string
The operator token. Returned only when creating the initial user.
requiresPasswordReset boolean
Whether the user must reset their password on next login. Present when the user has a username and password login identity.
updatedAt required integer <int64>
The Unix timestamp (seconds) when the user was last updated.
userId required integer <int64>
The numeric ID of the user.
username string
The user’s username. Present when the user has a username and password login identity.
Example request body
{
  "createdAt": 1717000000,
  "displayName": "Jane Smith",
  "requiresPasswordReset": false,
  "updatedAt": 1717000000,
  "userId": 1,
  "username": "jsmith"
}
400

Request failed. Possible reasons:

  • Invalid database name
  • Malformed request body
  • Invalid timestamp precision
data object
error string
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No user exists with the specified ID.
data object
error string
DELETE /api/v3/users/{id}

Delete a user

Soft deletes a user. A user can self-delete as long as they are not the last remaining user; the last user can only be deleted with an operator token. Deleting a user revokes all of that user’s refresh tokens.

Requires a token or user with permission to delete users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
id required integer <int64>
The numeric ID of the user to delete.
Example request Ask AI about this
curl --request DELETE \
  "https://localhost:8181/api/v3/users/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the deleted user with deletedAt set.
createdAt required integer <int64>
The Unix timestamp (seconds) when the user was created.
deletedAt integer <int64>
The Unix timestamp (seconds) when the user was deleted. Present only for deleted users.
displayName string
The user’s display name.
oauthId string
The user’s OAuth identity-provider ID. Present when the user has an OAuth login identity.
operatorToken string
The operator token. Returned only when creating the initial user.
requiresPasswordReset boolean
Whether the user must reset their password on next login. Present when the user has a username and password login identity.
updatedAt required integer <int64>
The Unix timestamp (seconds) when the user was last updated.
userId required integer <int64>
The numeric ID of the user.
username string
The user’s username. Present when the user has a username and password login identity.
Example request body
{
  "createdAt": 1717000000,
  "displayName": "Jane Smith",
  "requiresPasswordReset": false,
  "updatedAt": 1717000000,
  "userId": 1,
  "username": "jsmith"
}
401 Unauthorized access.
data object
error string
403 Access denied. The caller cannot delete their own account when they are the last remaining user, or lacks permission to delete users.
data object
error string
404 Not found. No user exists with the specified ID.
data object
error string
POST /api/v3/users/{id}/require-password-reset

Require a user to reset their password on next login

Marks the specified user as requiring a password reset. The user must set a new password before they are able to authenticate and receive a token.

Requires a token or user with permission to update users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
id required integer <int64>
The numeric ID of the user.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/users/{id}/require-password-reset" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the user with requiresPasswordReset set to true.
createdAt required integer <int64>
The Unix timestamp (seconds) when the user was created.
deletedAt integer <int64>
The Unix timestamp (seconds) when the user was deleted. Present only for deleted users.
displayName string
The user’s display name.
oauthId string
The user’s OAuth identity-provider ID. Present when the user has an OAuth login identity.
operatorToken string
The operator token. Returned only when creating the initial user.
requiresPasswordReset boolean
Whether the user must reset their password on next login. Present when the user has a username and password login identity.
updatedAt required integer <int64>
The Unix timestamp (seconds) when the user was last updated.
userId required integer <int64>
The numeric ID of the user.
username string
The user’s username. Present when the user has a username and password login identity.
Example request body
{
  "createdAt": 1717000000,
  "displayName": "Jane Smith",
  "requiresPasswordReset": false,
  "updatedAt": 1717000000,
  "userId": 1,
  "username": "jsmith"
}
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No user exists with the specified ID.
data object
error string
GET /api/v3/users/{id}/roles

List all roles assigned to a user

Lists all roles assigned to the specified user.

Requires a token or user with permission to read users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
id required integer <int64>
The numeric ID of the user.
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/users/{id}/roles" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the list of roles assigned to the user.
items required object[]
The roles assigned to the user.
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No user exists with the specified ID.
data object
error string
PUT /api/v3/users/{id}/roles

Replace all roles assigned to a user

Replaces all role assignments for the specified user with the provided list of role IDs. Roles not included in the request are removed from the user.

Requires a token or user with permission to update users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting --without-user-auth false.

Parameters

Path parameters
id required integer <int64>
The numeric ID of the user.

Request body required

Content-Type: application/json
roleIds required integer[]
The complete set of role IDs to assign to the user.
Example request body
{
  "roleIds": [
    1,
    2
  ]
}
Example request Ask AI about this
curl --request PUT \
  "https://localhost:8181/api/v3/users/{id}/roles" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"roleIds":[1,2]}'

Responses

200 Success. Returns the user’s updated role assignments.
items required object[]
The roles assigned to the user.
400

Request failed. Possible reasons:

  • Invalid database name
  • Malformed request body
  • Invalid timestamp precision
data object
error string
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No user exists with the specified ID.
data object
error string

Was this page helpful?

Thank you for your feedback!