# User Management

For MongoDB clusters, you have to manage users via the IONOS Cloud API and creating users inside the database is not possible. This document shows you in detail how to create, view, and delete users.

## Roles

In MongoDB most roles are scoped to a database. For example you grant `readWrite` permissions on database `mydb`. The exception are roles that grant permissions to all databases, for example [<mark style="color:blue;">readAnyDatabase</mark>](https://www.mongodb.com/docs/manual/reference/built-in-roles/?deployment-type=self#mongodb-authrole-readAnyDatabase).

Assignable roles have several restrictions to avoid customers breaking out of their database or breaking internal stuff:

* Currently, you can only assign [<mark style="color:blue;">built-in roles</mark>](https://www.mongodb.com/docs/manual/reference/built-in-roles/). Out of those currently only `read`, `readWrite`, `readAnyDatabase`, `readWriteAnyDatabase`, `dbAdmin`, `dbAdminAnyDatabase` and `clusterMonitor` are supported.
* Roles with the suffix `*AnyDatabase` are granted only on the `admin` database, which is the main user management database.
* Roles `read`, `readWrite` and `dbAdmin` cannot be granted on `config` and `local` databases.

## Add a user

When creating a user you need to consider the following:

* All users are created in the `admin` database.
* The combination of username and database must be unique within the MongoDB cluster.
* You can only change the assigned roles and the password of a user.
* You cannot have more than 100 users in a cluster.

To add users to a MongoDB cluster, use the `POST` request for each user.

### Endpoint

Use the following endpoint to add a user: `https://api.ionos.com/databases/mongodb/clusters/{clusterId}/users`

{% hint style="info" %}
**Note:** The sample cluster UUID is `498ae72f-411f-11eb-9d07-046c59cc737e`.
{% endhint %}

### Request

```bash
curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "metadata": {},
      "properties": {
        "username": "benjamin",
        "password": "password",
        "roles": [
          {
            "role": "readWrite",
            "database": "mydb"
          }
        ]
      }
    }' \
```

### Response

```json
{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "readWrite",
        "database": "mydb"
      }
    ]
  }
}
```

## Delete a user

To delete a user from MongoDB cluster, use the `DELETE` request.

### Endpoint

To delete a user from MongoDB cluster, use the DELETE request as follows: Use the following endpoint to delete a user: `https://api.ionos.com/databases/mongodb/clusters/{clusterId}/users/{username}`

{% hint style="info" %}
**Note:** The sample cluster UUID is `498ae72f-411f-11eb-9d07-046c59cc737e`.
{% endhint %}

### Request

```bash
curl --include \
    --request DELETE \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
```

### Response

```json
{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3"
  },
  "properties": {
    "username": "string",
    "roles": [
      {
        "role": "read",
        "database": "string"
      }
    ]
  }
}
```

## Get all users

To get a list of all users defined in MongoDB cluster, use the `GET` request.

### Endpoint

Use the following endpoint to get all users: `https://api.ionos.com/databases/mongodb/clusters/{clusterId}/users`

{% hint style="info" %}
**Note:** The sample cluster UUID is `498ae72f-411f-11eb-9d07-046c59cc737e`.
{% endhint %}

### Request

```bash
curl --include \
    --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
```

### Response

```json
{
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "type": "collection",
  "items": [
    {
      "type": "user",
      "metadata": {
        "createdDate": "2020-12-10T12:37:50.000Z",
        "createdBy": "clientname@ionos.com",
        "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
      },
      "properties": {
        "username": "benjamin",
        "roles": [
          {
            "role": "readWrite",
            "database": "mydb"
          }
        ]
      }
    }
  ]
}

```

## Get a single user

To get a specific user in a MongoDB cluster, use the `GET` request.

### Endpoint

Use the following endpoint to get a single user: `https://api.ionos.com/databases/mongodb/clusters/{clusterId}/users{username}`

{% hint style="info" %}
**Note:** The sample cluster UUID is `498ae72f-411f-11eb-9d07-046c59cc737e`.
{% endhint %}

### Request

```bash
curl --include \
    --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
```

### Response

```json
{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "readWrite",
        "database": "mydb"
      }
    ]
  }
}
```

## Modify a single user

### Change the password

To update the password of a specific user in a MongoDB cluster, use the `PATCH` request.

#### Endpoint

Use the following endpoint to change the password: `https://api.ionos.com/databases/mongodb/clusters/{clusterId}/users/{username}`

{% hint style="info" %}
**Note:** The sample cluster UUID is `498ae72f-411f-11eb-9d07-046c59cc737e`.
{% endhint %}

#### Request

```bash
curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "password": "new super secure password",
      }
    }' \
```

#### Response

```json
{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "readWrite",
        "database": "mydb"
      }
    ]
  }
}
```

### Update the roles

To update the assigned roles of a specific user in a MongoDB cluster, use the `PATCH` request with the new list of assigned roles. Note that the request replaces the old role list, meaning that any existing roles missing from the patch will be deleted.

#### Endpoint

Use the following endpoint to update the roles: `https://api.ionos.com/databases/mongodb/clusters/{clusterId}/users/{username}`

{% hint style="info" %}
**Note:** The sample cluster UUID is `498ae72f-411f-11eb-9d07-046c59cc737e`.
{% endhint %}

#### Request

```bash
curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "roles": [
          {"database": "mydb", "role": "read"}
        ]
      }
    }' \
```

#### Response

```json
{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "read",
        "database": "mydb"
      }
    ]
  }
}
```