---
title: Managing MongoDB® users with the Scaleway API
description: This page explains how to manage MongoDB® users via the API
tags: managed-database database postgresql mongodb database-instance mongodb
dates:
  validation: 2025-11-13
  posted: 2025-04-08
---

When you create your MongoDB® Database Instance, a default user with administrative privileges is automatically created.

You can create more users and grant them pre-set roles via the [Scaleway Managed MongoDB® API](https://www.scaleway.com/en/developers/api/managed-mongodb-databases/).

<Message type="important">
  All users you create initially have administrator roles, which can be modified after creation using the [Apply user roles](https://www.scaleway.com/en/developers/api/managed-mongodb-databases/#path-users-apply-user-roles) API call. However, the default user's role cannot be changed.
</Message>

### How to create a user

1. Edit the POST request payload you will use to create your user. Replace the values of each parameter with your values of choice following the parameter descriptions below.
    ```
      {
        "name": "<username>",
        "password": "<password>",
      }
    ```

    | Parameter        | Description                                                        |
    | :--------------- | :----------------------------------------------------------------- |
    | `name`     | Set a name for the database user. |
    | `password`           | Set a password for the database user.|

2. Run the following command to create a user. Make sure you include the payload you edited in the previous step. `{instance_id}` corresponds to the UUID of the Managed MongoDB®.
    ```
    curl -X POST \
      -H "X-Auth-Token: $SCW_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "<username>",
        "password": "<password>",
          }' \
      "https://api.scaleway.com/mongodb/v1alpha1/regions/$SCW_REGION/par/instances/{instance_id}/users"
    ```

    You should get a response like the following:
    ```
    {
      "name": "<username>",
      "password": "<password>",
        "roles": [
          {
            "role": "read_write",
            "any_database": true
          },
          {
            "role": "db_admin",
            "any_database": true
          },
          {
            "role": "sync",
            "any_database": true
          }
        ]
    }
    ```

All users you create will have the `read_write`, `db_admin` and `sync` roles on all databases by default.

You can follow the steps below to update a user's role(s) to the one(s) of your choice.

### How to apply a role to a user

1. Edit the POST request payload you will use to update the user role. Replace the values of each parameter with your values of choice following the parameter descriptions below.

    In this example, we define a single `read_write` role for the user. This role applies only in the `example-db` database.

    <Message type="tip">
      To grant the user this role in all databases, you can set `any_database` to true.
    </Message>

    ```
    {
      "name": "<username>",
      "roles": [
        {
          "role": "read_write",
          "database": "example-db",
          "any_database": false
        }
      ]
    }
    ```

    | Role        | Description                                                        |
    | :--------------- | :----------------------------------------------------------------- |
    | `read`     | Read privileges on all non-system collections and the `system.js` collection. Refer to the [official MongoDB® documentation](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) for an extensive list of the privileges granted to this role. |
    | `read_write`           | Read and write privileges on all non-system collections and the `system.js` collection. Refer to the [official MongoDB® documentation](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) for an extensive list of the privileges granted to this role. |
    | `db_admin`           | Privileges to perform administrative tasks on the database, such as schema-related tasks, indexing, and gathering statistics. This role does not grant privileges for user and role management. Refer to the [official MongoDB® documentation](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) for an extensive list of the privileges granted to this role. |
    | `sync`           | Role that aggregates three MongoDB roles:   |
    |            | `clusterMonitor` - Read-only access to monitoring tools. Refer to the [official MongoDB® documentation](https://www.mongodb.com/docs/upcoming/reference/built-in-roles/#mongodb-authrole-clusterMonitor) for an extensive list of the privileges granted to this role.  |
    |            | `backup` -  Grants the minimal privileges needed to back up data. Refer to the [official MongoDB® documentation](https://www.mongodb.com/docs/upcoming/reference/built-in-roles/#mongodb-authrole-backup) for an extensive list of the privileges granted to this role. |
    |            | `restore` - Grants the privileges needed to restore data from backups. Refer to the [official MongoDB® documentation](https://www.mongodb.com/docs/upcoming/reference/built-in-roles/#mongodb-authrole-restore) for an extensive list of the privileges granted to this role.   |

2. Run the following command to apply a new role to the user. Make sure you include the payload you edited in the previous step and that you replace the parameters in the call with your information. `{instance_id}` corresponds to the UUID of the Managed MongoDB®.

    ```
    curl -X PUT \
      -H "X-Auth-Token: $SCW_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "<username>",
        "roles": [
          {
            "role": "read_write",
            "database": "<name_of_database>"
            "any_database": false
          }
        ]
      }' \
      "https://api.scaleway.com/mongodb/v1alpha1/regions/$SCW_REGION/instances/{instance_id}/roles"
    ```

    If the call was successful, you will get the payload with the new role(s) as a response.

    <Message type="note">
      Assigning roles upon user creation will be possible by the second half of 2025. Refer to the [Scaleway Changelog](/changelog/?product=mongodb) to keep up with the latest Managed MongoDB® updates.
    </Message>