Documentation

Manage authorization with the InfluxDB Enterprise Meta API

Important
Authentication must be enabled before authorization can be managed. If authentication is not enabled, permissions will not be enforced. See “Enable authentication”.

Use the InfluxDB Enterprise Meta API to manage authorization for a cluster.

The API can be used to manage both cluster-wide and database-specific permissions. Chronograf can only manage cluster-wide permissions. To manage permissions at the database level, use the API.

For more information, see Enterprise users and permissions.

Example API requests

Many of the examples below use the jq utility to format JSON output for readability. Install jq to process JSON output. If you don’t have access to jq, remove the | jq shown in the example.

Users:

Roles:

Users

Use the /user endpoint of the InfluxDB Enterprise Meta API to manage users.

List users

View a list of existing users.

curl --location-trusted -u "admin:changeit" -s https://cluster_node_1:8091/user | jq
{
    "users": [
        {
            "hash": "$2a$10$NelNfrWdxubN0/TnP7DwquKB9/UmJnyZ7gy0i69MPldK73m.2WfCu",
            "name": "admin",
            "permissions": {
                "": [
                    "ViewAdmin",
                    "ViewChronograf",
                    "CreateDatabase",
                    "CreateUserAndRole",
                    "AddRemoveNode",
                    "DropDatabase",
                    "DropData",
                    "ReadData",
                    "WriteData",
                    "Rebalance",
                    "ManageShard",
                    "ManageContinuousQuery",
                    "ManageQuery",
                    "ManageSubscription",
                    "Monitor",
                    "CopyShard",
                    "KapacitorAPI",
                    "KapacitorConfigAPI"
                ]
            }
        }
    ]
}
Create a user against a follower node

Transactions that modify the user store must be sent to the lead meta node using POST.

If the node returns a 307 redirect message, try resending the request to the lead node as indicated by the Location field in the HTTP response header.

curl --location-trusted -u "admin:changeit" -s -v \
  -d '{"action":"create","user":{"name":"phantom2","password":"changeit"}}' \
  https://cluster_node_2:8091/user
Create a user against the lead node
curl --location-trusted -u "admin:changeit" -s -v \
  -d '{"action":"create","user":{"name":"phantom","password":"changeit"}}' \
  https://cluster_node_1:8091/user
Retrieve a user details document
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | jq
{
    "users": [
        {
            "hash": "$2a$10$hR.Ih6DpIHUaynA.uqFhpOiNUgrADlwg3rquueHDuw58AEd7zk5hC",
            "name": "phantom"
        }
    ]
}
Grant permissions to a user for all databases

To grant a list of permissions for all databases in a cluster, use the "" key in the permissions object, as shown in the example below.

curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"add-permissions","user":{"name":"phantom","permissions":{"":["ReadData", "WriteData"]}}}' \
  https://cluster_node_1:8091/user
Grant permissions to a user for a specific database

Grant ReadData and WriteData permissions to the user named phantom for MyDatabase.

curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"add-permissions","user":{"name":"phantom","permissions":{"MyDatabase":["ReadData","WriteData"]}}}' \
  https://cluster_node_1:8091/user
Verify user permissions
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | jq
{
    "users": [
        {
            "hash": "$2a$10$hR.Ih6DpIHUaynA.uqFhpOiNUgrADlwg3rquueHDuw58AEd7zk5hC",
            "name": "phantom",
            "permissions": {
                "MyDatabase": [
                    "ReadData",
                    "WriteData"
                ]
            }
        }
    ]
}
Remove permissions from a user
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"remove-permissions","user":{"name":"phantom","permissions":{"":["KapacitorConfigAPI"]}}}' \
  https://cluster_node_1:8091/user
Remove a user
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"delete","user":{"name":"phantom2"}}' \
  https://cluster_node_1:8091/user
Verify user removal
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom
{
    "error": "user not found"
}
Change a user’s password
curl --location-trusted -u "admin:changeit" -H "Content-Type: application/json" \
  -d '{"action": "change-password", "user": {"name": "<username>", "password": "newpassword"}}' \
  localhost:8091/user

Roles

The Influxd-Meta API provides an endpoint /role for managing roles.

List roles
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | jq
{}

In a fresh installation no roles will have been created yet. As when creating a user the lead node must be used.

Create a role
curl --location-trusted --negotiate -u "admin:changeit" -v \
  -d '{"action":"create","role":{"name":"spectre"}}' \
  https://cluster_node_1:8091/role
Verify roles

Verify the role has been created.

curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | jq
{
    "roles": [
        {
            "name": "djinn",
        },
        {
            "name": "spectre"
        },
    ]
}
Retrieve a role document

Retrieve a record for a single node.

curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
{
   "roles": [
       {
           "name": "spectre"
       }
   ]
}
Add permissions to a role for all databases

To grant a list of permissions to a role for all databases in a cluster, use the "" key in the permissions object, as shown in the example below.

curl --location-trusted --negotiate -u "admin:changeit" -s -v \
   -d '{"action":"add-permissions","role":{"name":"spectre","permissions":{"":["ReadData","WriteData"]}}}' \
   https://cluster_node_1:8091/role
Add permissions to a role for a specific database

Grant ReadData and WriteData permissions to the role named spectre for MyDatabase.

curl --location-trusted --negotiate -u "admin:changeit" -s -v \
   -d '{"action":"add-permissions","role":{"name":"spectre","permissions":{"MyDatabase":["ReadData","WriteData"]}}}' \
   https://cluster_node_1:8091/role
Verify role permissions

Verify permissions have been added.

curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
{
    "roles": [
        {
            "name": "spectre",
            "permissions": {
                "MyDatabase": [
                    "ReadData",
                    "WriteData"
                ]
            }
        }
    ]
}
Add a user to a role
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"add-users","role":{"name":"spectre","users":["phantom"]}}' \
  https://cluster_node_1:8091/role
Verify user in role

Verify user has been added to role.

curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
{
    "roles": [
        {
            "name": "spectre",
            "permissions": {
                "": [
                    "KapacitorAPI",
                    "KapacitorConfigAPI"
                ]
            },
            "users": [
                "phantom"
            ]
        }
    ]
}
Remove a user from a role
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"remove-users","role":{"name":"spectre","users":["phantom"]}}' \
  https://admin:changeit@cluster_node_1:8091/role
Remove a permission from a role
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"remove-permissions","role":{"name":"spectre","permissions":{"":["KapacitorConfigAPI"]}}}' \
  https://cluster_node_1:8091/role
Delete a role
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"delete","role":{"name":"spectre"}}' \
  https://cluster_node_1:8091/role
Verify role deletion
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
{
    "error": "role not found"
}

Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements


InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered