---
title: Manage authorization with the InfluxDB Enterprise v1 Meta API
description: Manage users and permissions with the InfluxDB Enterprise v1 Meta API.
url: https://docs.influxdata.com/enterprise_influxdb/v1/administration/manage/users-and-permissions/authorization-api/
estimated_tokens: 7399
product: InfluxDB Enterprise v1
version: v1
---

# Manage authorization with the InfluxDB Enterprise v1 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”](/enterprise_influxdb/v1/administration/configure/security/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](/enterprise_influxdb/v1/administration/manage/users-and-permissions/permissions/#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](/enterprise_influxdb/v1/administration/manage/users-and-permissions/permissions/).

### Example API requests

Many of the examples below use the `jq` utility to format JSON output for readability. [Install `jq`](https://stedolan.github.io/jq/download/) to process JSON output. If you don’t have access to `jq`, remove the `| jq` shown in the example.

**Users**:

-   [List users](#list-users)
-   [Create a user against a follower node](#create-a-user-against-a-follower-node)
-   [Create a user against the lead node](#create-a-user-against-the-lead-node)
-   [Retrieve a user details document](#retrieve-a-user-details-document)
-   [Grant permissions to a user for all databases](#grant-permissions-to-a-user-for-all-databases)
-   [Grant permissions to a user for a specific database](#grant-permissions-to-a-user-for-a-specific-database)
-   [Verify user permissions](#verify-user-permissions)
-   [Remove permissions from a user](#remove-permissions-from-a-user)
-   [Remove a user](#remove-a-user)
-   [Verify user removal](#verify-user-removal)
-   [Change a user’s password](#change-a-users-password)

**Roles**:

-   [List roles](#list-roles)
-   [Create a role](#create-a-role)
-   [Verify roles](#verify-roles)
-   [Retrieve a role document](#retrieve-a-role-document)
-   [Add permissions to a role for all databases](#add-permissions-to-a-role-for-all-databases)
-   [Add permissions to a role for a specific database](#add-permissions-to-a-role-for-a-specific-database)
-   [Verify role permissions](#verify-role-permissions)
-   [Add a user to a role](#add-a-user-to-a-role)
-   [Verify user in role](#verify-user-in-role)
-   [Remove a user from a role](#remove-a-user-from-a-role)
-   [Remove a permission from a role](#remove-a-permission-from-a-role)
-   [Delete a role](#delete-a-role)
-   [Verify role deletion](#verify-role-deletion)

#### Users

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

##### List users

View a list of existing users.

```sh
curl --location-trusted -u "admin:changeit" -s https://cluster_node_1:8091/user | jq
```

```json
{
    "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.

```sh
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

```sh
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

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | jq
```

```json
{
    "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

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | jq
```

```json
{
    "users": [
        {
            "hash": "$2a$10$hR.Ih6DpIHUaynA.uqFhpOiNUgrADlwg3rquueHDuw58AEd7zk5hC",
            "name": "phantom",
            "permissions": {
                "MyDatabase": [
                    "ReadData",
                    "WriteData"
                ]
            }
        }
    ]
}
```

##### Remove permissions from a user

```sh
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

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"delete","user":{"name":"phantom2"}}' \
  https://cluster_node_1:8091/user
```

##### Verify user removal

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom
```

```json
{
    "error": "user not found"
}
```

##### Change a user’s password

```sh
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

```sh
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

```sh
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.

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | jq
```

```json
{
    "roles": [
        {
            "name": "djinn"
        },
        {
            "name": "spectre"
        }
    ]
}
```

##### Retrieve a role document

Retrieve a record for a single node.

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
```

```json
{
   "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.

```sh
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`.

```sh
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.

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
```

```json
{
    "roles": [
        {
            "name": "spectre",
            "permissions": {
                "MyDatabase": [
                    "ReadData",
                    "WriteData"
                ]
            }
        }
    ]
}
```

##### Add a user to a role

```sh
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.

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
```

```json
{
    "roles": [
        {
            "name": "spectre",
            "permissions": {
                "": [
                    "KapacitorAPI",
                    "KapacitorConfigAPI"
                ]
            },
            "users": [
                "phantom"
            ]
        }
    ]
}
```

##### Remove a user from a role

```sh
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

```sh
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

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s -v \
  -d '{"action":"delete","role":{"name":"spectre"}}' \
  https://cluster_node_1:8091/role
```

##### Verify role deletion

```sh
curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | jq
```

```json
{
    "error": "role not found"
}
```