# User

To use the User API, it's necessary to generate an access token.

{% content-ref url="/pages/pWMV9FXn2PVthWicFKyC" %}
[Access Token](/manual/implementation/platform-usage/api-reference/access-token.md)
{% endcontent-ref %}

{% hint style="info" %}
A comprehensive toolkit, with practical usage examples, is accessible on [GitHub](https://github.com/datasentinel/datasentinel_toolkit).

This toolkit comes pre-installed as a default component within the on-premises platform, located at `/datasentinel/soft/datasentinel_toolkit`.
{% endhint %}

## **User**

### Add

<mark style="color:green;">`POST`</mark> `https://<<platform-server>>/ds-api/users/{email}`

Create a User

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| email<mark style="color:red;">\*</mark> | String |             |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

#### Request Body

<table><thead><tr><th>Name</th><th width="251">Type</th><th>Description</th></tr></thead><tbody><tr><td>password</td><td>String</td><td>User Password<br><br><strong>Required</strong> for Regular users</td></tr><tr><td>privilege</td><td>String</td><td>Possible values:<br>read, read write or admin<br><br>Default: <strong>admin</strong></td></tr><tr><td>profile</td><td>String</td><td>Possible values:<br>developer or data admin<br><br>Default: <strong>data admin</strong></td></tr><tr><td>live_360</td><td>String</td><td>Access to <a href="/pages/6m2QWxqCtnDKY67DLi9v">Live360 Feature</a><br><br>Possible values: 0 or 1<br><br>Default: <strong>1</strong></td></tr><tr><td>roles</td><td>String array</td><td><strong>Since version 2024.04</strong><br><br>Roles used for <a href="/pages/Ba2AZyCDjN74kY33kNjB">Role Based Access Control</a></td></tr><tr><td><del>role</del></td><td><del>String</del></td><td><em><strong>Deprecated</strong></em><br><em><strong>since version 2024.04</strong></em><br><em><strong>use roles instead</strong></em><br><br>Role used for <a href="/pages/Ba2AZyCDjN74kY33kNjB">Role Based Access Control</a><br><br>Default: <strong>No restriction</strong></td></tr><tr><td>comment</td><td>String</td><td></td></tr><tr><td>ldap</td><td>Boolean</td><td>Default: <strong>false</strong><br></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="201: Created " %}

```json
{
  "status": "User with login <<user>> created successfully"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="409: Conflict " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

**Two Flavors of User Access**

* **Regular Users: The Standard Access.**\
  You need to specify a password

{% code title="JSON body example" %}

```json
{
  "password": "myPassword",
  "privilege": "admin",
  "profile": "data admin",
  "live_360": 1,
  "roles": ["role_1", "role_2"],
  "comment": "My comment"
}

```

{% endcode %}

* **LDAP Users: For Seamless Network Integration**\
  You need to set the ldap value to **true.**

This POST request assigns privileges to a user authenticated through LDAP.

{% code title="JSON body example" %}

```json
{
  "ldap": true,
  "privilege": "admin",
  "profile": "data admin",
  "live_360": 1,
  "roles": [],
  "comment": "My comment"
}
```

{% endcode %}

{% hint style="info" %}
Refer to the [Documention](/manual/implementation/platform-usage/configuration/ldap.md) on setting up LDAP authentication
{% endhint %}

### Display

<mark style="color:blue;">`GET`</mark> `https://<<platform-server>>/ds-api/users/{email}`

Display User Attributes

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| email<mark style="color:red;">\*</mark> | String |             |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK " %}
{% code title="Example" %}

```json
{
    "id": 54,
    "login": "username",
    "email": "userName@myCompany.com",
    "profile": "data admin",
    "privilege": "admin",
    "roles": ["role_1", "role_2"],
    "live_360": 1,
    "comment": "My comment"
}
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

### Update

<mark style="color:orange;">`PUT`</mark> `https://<<platform-server>>/ds-api/users/{email}`

Update User Properties

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| email<mark style="color:red;">\*</mark> | String |             |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

#### Request Body

| Name      | Type         | Description                                                                                                                                                                                                                                                                            |
| --------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| password  | String       | User Password                                                                                                                                                                                                                                                                          |
| privilege | String       | <p>Possible values:<br>read, read write or admin<br><br>Default: <strong>admin</strong></p>                                                                                                                                                                                            |
| profile   | String       | <p>Possible values:<br>developer or data admin<br><br>Default: <strong>data admin</strong></p>                                                                                                                                                                                         |
| live\_360 | String       | <p>Access to <a href="/pages/6m2QWxqCtnDKY67DLi9v">Live360 Feature</a><br><br>Possible values: 0 or 1<br><br>Default: <strong>1</strong></p>                                                                                                                                           |
| roles     | String array | <p><em><strong>Since version 2024.04</strong></em><br><br>Roles used for <a href="/pages/Ba2AZyCDjN74kY33kNjB">Role Based Access Control</a></p>                                                                                                                                       |
| ~~role~~  | ~~String~~   | <p><em><strong>Deprecated</strong></em><br><em><strong>since version 2024.04</strong></em><br><em><strong>use roles instead</strong></em><br><br>Role used for <a href="/pages/Ba2AZyCDjN74kY33kNjB">Role Based Access Control</a><br><br>Default: <strong>No restriction</strong></p> |
| comment   | String       |                                                                                                                                                                                                                                                                                        |

**Response**

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "status": "User updated successfully!"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

### Delete

<mark style="color:red;">`DELETE`</mark> `https://<<platform-server>>/ds-api/users/{email}`

Delete User

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| email<mark style="color:red;">\*</mark> | String |             |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK " %}
{% code title="Example" %}

```json
{
  "message": "User deleted"
}
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

### Assign role

<mark style="color:green;">`POST`</mark> `https://<<platform-server>>/ds-api/users/{email}/role/{role name}`

Add an existing role to a user

#### Path Parameters

| Name                                    | Type   | Description   |
| --------------------------------------- | ------ | ------------- |
| email<mark style="color:red;">\*</mark> | String |               |
| role name                               | String | Existing role |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="201: OK" %}

```json
{
    "status": "Role role_2 has been assigned to myUser@datasentinel.io"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="400" %}

```json
```

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

### Remove role

<mark style="color:red;">`DELETE`</mark> `https://<<platform-server>>/ds-api/users/{email}/role/{role name}`

Remove an existing role from a user

#### Path Parameters

| Name                                    | Type   | Description   |
| --------------------------------------- | ------ | ------------- |
| email<mark style="color:red;">\*</mark> | String |               |
| role name                               | String | Existing role |

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "status": "Role role_2 has been removed from myUser@datasentinel.io"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}

## Users

### Display

<mark style="color:blue;">`GET`</mark> `https://<<platform-server>>/ds-api/users`

Display All Users

#### Headers

| Name                                         | Type   | Description            |
| -------------------------------------------- | ------ | ---------------------- |
| user-token<mark style="color:red;">\*</mark> | String | Generated Access Token |

**Response**

{% tabs %}
{% tab title="200: OK " %}
{% code title="Example" %}

```json
 [
    {
        "id": 2,
        "login": "datasentinel",
        "email": "contact@datasentinel.io",
        "profile": "data admin",
        "privilege": "admin",
        "roles": [],
        "live_360": 1,
        "comment": ""
    },
    {
        "id": 54,
        "login": "username",
        "email": "userName@myCompany.com",
        "profile": "data admin",
        "privilege": "read",
        "roles": ["role_1", "role_2"],
        "live_360": 0,
        "comment": ""
    }
]
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="500: Internal Server Error Internal error" %}

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.datasentinel.io/manual/implementation/platform-usage/api-reference/user.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.