# User

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

{% content-ref url="access-token" %}
[access-token](https://docs.datasentinel.io/manual/implementation/platform-usage/api-reference/access-token)
{% 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="../../../features/key-features/live360">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="../../../features/other-features/role-based-access">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="../../../features/other-features/role-based-access">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&#x20;

{% 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** \
  &#x20;You need to set the ldap value to **true.** &#x20;

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](https://docs.datasentinel.io/manual/implementation/platform-usage/configuration/ldap) 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="../../../features/key-features/live360">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="../../../features/other-features/role-based-access">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="../../../features/other-features/role-based-access">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 %}