# Manage Users and Role-Based Access

<div data-with-frame="true"><figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2Fmau9Q81uYBSQFMHSOv6j%2Frole-based-access.png?alt=media&#x26;token=f265d0e9-41a9-47ac-9b81-c7afad43bd1c" alt="Role Based Access Control"><figcaption></figcaption></figure></div>

Datasentinel secures access through a credential-based login process and supports LDAP and Active Directory integration for centralized authentication.

Using role-based access control (RBAC) combined with instance tags, administrators can precisely control user access based on organizational needs, such as application ownership, cluster scope, or environment type.

## Users

### Default Administrator Account

When Datasentinel is installed, a default administrator account named **`datasentinel`** is created. This account is granted full administrative privileges.

Administrators can use this account to:

* Create and manage users
* Define and assign roles
* Configure access control settings

### Profiles

Datasentinel provides **two user profiles** that control access to dashboards and reports.

<table><thead><tr><th width="173">Profile</th><th>Description</th></tr></thead><tbody><tr><td><strong>developer</strong></td><td>Limited access to the <a href="../features/key-features/top-queries"><em>Top Queries</em></a>, <a href="../features/key-features/session-history"><em>Session History</em></a>, and <a href="../features/key-features/top-tables"><em>Top Tables / Indexes</em></a> dashboards, as well as the corresponding <a href="../features/key-features/reporting">PDF reports</a></td></tr><tr><td><strong>data admin</strong></td><td>Full access to all dashboards and PDF reports</td></tr></tbody></table>

**Default profile:** `data admin`

### Privileges

Privileges define the actions a user is allowed to perform on the platform.

<table><thead><tr><th width="178">Privilege</th><th>Description</th></tr></thead><tbody><tr><td><strong>read</strong></td><td>Read-only access to the platform</td></tr><tr><td><strong>read write</strong></td><td>Read access plus the ability to terminate sessions or backends from the UI</td></tr><tr><td><strong>admin</strong></td><td>Read-write privileges plus full platform administration</td></tr></tbody></table>

**Default privilege:** `admin`

### Live360 Access

Access to the [**Live360** feature](https://docs.datasentinel.io/manual/features/key-features/live360) (direct access to PostgreSQL instances) can be enabled or disabled per user.

* **Enabled by default**
* Can be restricted for security or operational reasons

### User Dashboard

All user accounts and their associated profiles, privileges, roles, and Live360 access settings are managed from the **Users** dashboard.

<div data-with-frame="true"><figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2F84mvHgGV0neejOQFwuEB%2Fusers.png?alt=media&#x26;token=40828568-7bce-4dc2-8fc9-4bc4eedf8107" alt=""><figcaption></figcaption></figure></div>

## Roles

A **role** in Datasentinel defines a set of access rules based on instance tags.

Roles are created by associating one or more tag keys with specific values. These tag-based rules determine which PostgreSQL clusters are accessible to users assigned to the role.

By associating roles with users, administrators can restrict access to specific clusters in Datasentinel without managing permissions on a per-instance basis.

{% hint style="info" %}
When creating a role, each tag key/value pair used in the role definition must already exist on at least one monitored instance.

After a role is created, any new instance whose tags match the role rules is automatically included in the set of instances authorized by that role.
{% endhint %}

Role management is available through both the platform UI and the [API](https://docs.datasentinel.io/manual/implementation/platform-usage/api-reference/role).

<div data-with-frame="true"><figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2FMVKPWE5p0qu8Y7bNMmk6%2Frole-based-access-multi.png?alt=media&#x26;token=ecaa5f87-d89b-43a6-b8cc-da9a1c68bdd5" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
You can associate multiple tags to the same role and combine AND/OR conditions
{% endhint %}

## Associating Roles with Users

Once a role is defined, it can be associated with one or more users.

* A user can have **multiple roles**
* The user’s effective access is the **union of all role scopes**
* Removing a role immediately revokes access to the corresponding instances

This model allows flexible access patterns without duplicating role definitions.

## API-Based Configuration Example

This example shows how to configure access programmatically using the API.<br>

The goal is to create a user who has access only to PostgreSQL instances associated with the **`sales`** application, based on tag-based role assignment.

{% stepper %}
{% step %}

### Generate an API Access Token

An administrator account generates a temporary access token by authenticating with valid credentials.

**Request**

```bash
curl -sk -u datasentinel:$PASSWORD \
  -X POST https://$DATASENTINEL_HOST/ds-api/user-token
```

**Response**

```json
{
  "user-token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MjY3OTg1MjIsImlhdCI6MTYyNjcxMjExNywiZGF0YWJhc2UiOiJkcy1kYXRhIiwiZW1haWwiOiJjb250YWN0QGRhdGFzZW50aW5lbC5pbyIsInVzZXIiOiJkYXRhc2VudGluZWwifQ.YhKtqrx0O3_gw63dIFCW30ScI8yS-_QY1dss3rRNZNI"
}
```

The returned access token is valid for **24 hours** and must be included in the `Authorization` header of subsequent API calls.
{% endstep %}

{% step %}

### Declare a PostgreSQL Instance

In this step, an instance is declared associated with tags at creation time.

**Create the instance declaration payload**

```bash
TMP_JSON_FILE=/tmp/connection.json
CONNECTION_NAME=pg-sales-production

cat > $TMP_JSON_FILE <<EOF
{
  "host": "51.158.70.115",
  "port": 9342,
  "user": "datasentinel",
  "password": "sentinel",
  "tags": "application=sales"
}
EOF
```

The instance is tagged with `application=sales`. This tag will later be used by role definitions to control user access.

**Register the instance using the API**

```bash
curl -sk \
  --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/pool/pg-instances/$CONNECTION_NAME \
  -d @$TMP_JSON_FILE
```

**Response**

```json
{
  "status": "Connection created and connected!"
}
```

Once registered, the instance is immediately available in Datasentinel and automatically included in any role whose tag rules match `application=sales`.

#### Agentless vs Agent-Based Monitoring

This example demonstrates [agentless monitoring](https://docs.datasentinel.io/manual/features/other-features/agentless-monitoring), where PostgreSQL instances are declared directly through the API and monitored by Datasentinel platform.

When using [local agents](https://docs.datasentinel.io/manual/getting-started/installation/agent), instance declaration and tag configuration are handled at the agent level. Refer to the documentation for details on [agent-based configuration](https://docs.datasentinel.io/manual/getting-started/postgresql-clusters/adding-connection).
{% endstep %}

{% step %}

### Create a Role

In this step, a role is created using the [API](https://docs.datasentinel.io/manual/implementation/platform-usage/api-reference/role).\
The role is defined using tag-based rules and will grant access only to PostgreSQL instances whose tags match those rules.

In this example, the role allows access to instances tagged with:

* `application=sales`

**Role definition payload**

<pre class="language-bash"><code class="lang-bash"><strong>TMP_JSON_FILE=/tmp/role.json
</strong>ROLE_NAME=sales-role

cat > $TMP_JSON_FILE &#x3C;&#x3C;EOF
{
  "name": "sales-role",
  "description": "Access restricted to PostgreSQL instances tagged with application=sales",
  "tags": {
    "application": ["sales"]
  }
}
EOF
</code></pre>

The `tags` section defines the role scope.\
Only instances whose tags match defined conditions are included in the role.

**Create the role using the API**

```bash
curl -sk \
  --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/roles \
  -d @$TMP_JSON_FILE
```

**Response**

```json
{
  "status": "Role created successfully"
}
```

Once created, the role dynamically applies to:

* All existing instances tagged with `application=sales`
* Any future instance registered with the same tag
  {% endstep %}

{% step %}

### Create a User and Assign a Role

In this step, a user account is created through the [API ](https://docs.datasentinel.io/manual/implementation/platform-usage/api-reference/user)and associated with the role defined.

The user is identified by an email address and inherits access restrictions from the assigned role. \
\
In this example, the user will have access **only to PostgreSQL instances tagged with `application=sales`**.

**User definition payload**

```bash
TMP_JSON_FILE=/tmp/user.json
ROLE_NAME="sales-role"
USER_EMAIL="jean.lapioffe@company.com"

cat > $TMP_JSON_FILE <<EOF
{
  "password": "myPassword",
  "role": "$ROLE_NAME"
}
EOF
```

The role association in the payload determines the scope of instances visible to the user.

**Create the user**

```bash
curl -sk \
  --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/users/$USER_EMAIL \
  -d @$TMP_JSON_FILE
```

**Response**

```json
{
  "status": "User with login jean.lapioffe created successfully"
}
```

The user can sign in using the specified email address and will have access only to PostgreSQL instances tagged with `application=sales`.

<div data-with-frame="true"><figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2FbP2iz1glmQvZGxlMa3sb%2Frole-based-access-user.png?alt=media&#x26;token=6d313d96-a88b-4085-b171-ae665dc3bb23" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
When creating a role, the referenced tag key/value pairs must already exist on at least one monitored instance. After role creation, any new instance matching the role rules is automatically included in the role scope.
{% endhint %}

## Common Use Cases

### Development-only access

Grant developers access only to non-production environments.

**Role definition:**

* `environment=development`

**Result:**

* The user can view metrics, sessions, and queries only for development instances.

***

### Application-based access

Restrict access to a specific application across all environments.

**Role definition:**

* `application=inventory`

**Result:**

* The user can access all PostgreSQL instances related to the *inventory* application.

***

### Primary and replica visibility

Grant access to both a primary instance and its read-only replicas.

**Role definition:**

* `cluster=orders`

**Result:**

* The user can analyze the consolidated workload across the primary and replica instances.

### Best Practices for Role-Based Access Control

{% content-ref url="../implementation/platform-usage/configuration/default-rbac-behavior" %}
[default-rbac-behavior](https://docs.datasentinel.io/manual/implementation/platform-usage/configuration/default-rbac-behavior)
{% endcontent-ref %}

To ensure secure and maintainable access control:

* Define a **standard tagging strategy** (environment, application, owner, cluster)
* Use **tags as the single source of truth** for access control
* Review roles and user assignments regularly

Consistent tagging is essential for predictable RBAC behavior.

## Conclusion

Datasentinel enables fine-grained control of user access to PostgreSQL instances through tag-based roles, configurable via both the UI and the API for automation.