--- title: User management description: 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. url: https://docs.influxdata.com/influxdb3/enterprise/api/user-management/ estimated_tokens: 3487 product: InfluxDB 3 Enterprise version: enterprise publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/enterprise/api/user-management/ --- [Download InfluxDB 3 Enterprise API Spec](/openapi/influxdb3-enterprise-openapi.yml) 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`requiredstring The name of the role to retrieve. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/roles_by_name/{roleName}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the matching role. `createdAt`requiredinteger \ The Unix timestamp (seconds) when the role was created. `description`string The role description. `id`requiredinteger \ The numeric ID of the role. `isRequiredRole`requiredboolean Whether the role is a required role. `name`requiredstring The role name. `updatedAt`requiredinteger \ The Unix timestamp (seconds) when the role was last updated. Example request body ```json { "createdAt": 1717000000, "id": 1, "isRequiredRole": false, "name": "read-write", "updatedAt": 1717000000 } ``` 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not 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`requiredinteger \ The ID of the role. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/roles/{id}/permissions" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the role’s permissions. `permissions`requiredobject[] The permissions granted to the role. 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not 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`requiredstring The OAuth identity-provider ID of the user. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/users_by_oauth_id/{oauth_id}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the matching user. `createdAt`requiredinteger \ The Unix timestamp (seconds) when the user was created. `deletedAt`integer \ 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`requiredinteger \ The Unix timestamp (seconds) when the user was last updated. `userId`requiredinteger \ 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 ```json { "createdAt": 1717000000, "displayName": "Jane Smith", "requiresPasswordReset": false, "updatedAt": 1717000000, "userId": 1, "username": "jsmith" } ``` 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not 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`requiredinteger \ The numeric ID of the user to update. #### Request bodyrequired Content-Type:`application/json` `displayName`string The user’s new display name. Example request body ```json { "displayName": "Jane Smith" } ``` Example request[Ask AI about this](#) ```sh 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 200Success. Returns the updated user. `createdAt`requiredinteger \ The Unix timestamp (seconds) when the user was created. `deletedAt`integer \ 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`requiredinteger \ The Unix timestamp (seconds) when the user was last updated. `userId`requiredinteger \ 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 ```json { "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 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not 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`requiredinteger \ The numeric ID of the user to delete. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/users/{id}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the deleted user with `deletedAt` set. `createdAt`requiredinteger \ The Unix timestamp (seconds) when the user was created. `deletedAt`integer \ 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`requiredinteger \ The Unix timestamp (seconds) when the user was last updated. `userId`requiredinteger \ 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 ```json { "createdAt": 1717000000, "displayName": "Jane Smith", "requiresPasswordReset": false, "updatedAt": 1717000000, "userId": 1, "username": "jsmith" } ``` 401Unauthorized access. `data`object `error`string 403Access 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 404Not 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`requiredinteger \ The numeric ID of the user. Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/users/{id}/require-password-reset" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the user with `requiresPasswordReset` set to `true`. `createdAt`requiredinteger \ The Unix timestamp (seconds) when the user was created. `deletedAt`integer \ 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`requiredinteger \ The Unix timestamp (seconds) when the user was last updated. `userId`requiredinteger \ 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 ```json { "createdAt": 1717000000, "displayName": "Jane Smith", "requiresPasswordReset": false, "updatedAt": 1717000000, "userId": 1, "username": "jsmith" } ``` 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not 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`requiredinteger \ The numeric ID of the user. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/users/{id}/roles" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the list of roles assigned to the user. `items`requiredobject[] The roles assigned to the user. 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not 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`requiredinteger \ The numeric ID of the user. #### Request bodyrequired Content-Type:`application/json` `roleIds`requiredinteger[] The complete set of role IDs to assign to the user. Example request body ```json { "roleIds": [ 1, 2 ] } ``` Example request[Ask AI about this](#) ```sh 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 200Success. Returns the user’s updated role assignments. `items`requiredobject[] The roles assigned to the user. 400 Request failed. Possible reasons: * Invalid database name * Malformed request body * Invalid timestamp precision `data`object `error`string 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not found. No user exists with the specified ID. `data`object `error`string #### Related * [InfluxDB 3 API client libraries](/influxdb3/enterprise/reference/client-libraries/v3/)