v9 (current) v8
Edit Page

User Management RESTHeart Cloud

🔧 Configuration

▼
Sets localhost:8080 with admin:secret
Values are saved in your browser

⚡ Setup Guide

▼

To run the examples on this page, you need a RESTHeart instance.

Option 1: Use RESTHeart Cloud (Recommended)

The fastest way to get started is with RESTHeart Cloud. Create a free service in minutes:

  1. Sign up at cloud.restheart.com

  2. Create a free API service

  3. Set up your root user following the Root User Setup guide

  4. Use the configuration panel above to set your service URL and credentials

Tip
 All code examples on this page will automatically use your configured RESTHeart Cloud credentials.

Option 2: Run RESTHeart Locally

If you prefer local development, follow the Setup Guide to install RESTHeart on your machine.

Note
 Local instances run at http://localhost:8080 with default credentials admin:secret

What You’ll Learn

In this guide, you’ll learn how to:

  1. Understand the user document structure

  2. Create new users with roles and passwords

  3. Retrieve existing user information

  4. Update user properties and passwords

  5. Delete users from the system

  6. Manage user roles and permissions

By the end, you’ll be able to fully manage user accounts in RESTHeart.

Note

In all examples below:

  • [RESTHEART-URL] - Replace with your RESTHeart server URL (e.g., http://localhost:8080)

  • [BASIC-AUTH] - Replace with your Base64-encoded credentials (e.g., YWRtaW46c2VjcmV0 for admin:secret)

The interactive examples on this page can automatically substitute these values.

Introduction

This section provides instructions on how to create, update and delete users with the default authenticator mongoRealAuthenticator.

It also shows how to manage permissions with the default authorizer mongoAclAuthorizer.

Note
 The mongoRealAuthenticator is configured to utilize the "/users" collection as its default storage location for user documents. Similarly, the mongoAclAuthorizer employs the "/acl" collection as its default repository for storing permissions.

User document

With the default configuration, a user is represented as follows:

{
    "_id": "username",
    "roles": [ "list", "of", "roles" ],
    "password": "secret"
}
Tip
 mongoRealAuthenticator can be configured to use different properties for the username, roles an password. Check mongoRealAuthenticator for more information.

Get existing users

cURL

curl -i -X GET [RESTHEART-URL]/users -H "Authorization: Basic [BASIC-AUTH]" \

HTTPie

http GET [RESTHEART-URL]/users Authorization:"Basic [BASIC-AUTH]"

JavaScript

const username = 'your-username';
const password = 'your-password';
const credentials = btoa(`${username}:${password}`);

fetch('[RESTHEART-URL]/users', {
    method: 'GET',
    headers: {
        'Authorization': `Basic ${credentials}`
    }
})
.then(response => response.json())
.then(data => {
    console.log('Retrieved users:', data);
})
.catch(error => console.error('Error:', error));
[
  {
    "_id": "admin",
    "roles": [
      "admin"
    ],
    "_etag": {
      "$oid": "5d2edb155883c050065d6a8a"
    }
  }
]
Note
 The password is always hidden on GET requests.
Note
 For security reasons, it not possible to use the filter query parameter on the password field; the following request is forbidden and will cause an error: GET /users?filter={"password":{"$regex":"^a.*"}}

Create a user

cURL

curl -i -X POST [RESTHEART-URL]/users \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "foo",
    "roles": [ "user" ],
    "password": "secret"
}'

HTTPie

http POST [RESTHEART-URL]/users \
  Authorization:"Basic [BASIC-AUTH]" \
  Content-Type:application/json \
  _id="foo" \
  roles:='["user"]' \
  password="secret"

JavaScript

const username = 'your-username';
const password = 'your-password';
const credentials = btoa(`${username}:${password}`);

fetch('[RESTHEART-URL]/users', {
    method: 'POST',
    headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "_id": "foo",
        "roles": [ "user" ],
        "password": "secret"
    })
})
.then(response => {
    if (response.ok) {
        console.log('User created successfully');
    } else {
        console.error('Failed to create user:', response.status);
    }
})
.catch(error => console.error('Error:', error));
Note
 The password is automatically encrypted by RESTHeart.

Update a user

cURL

curl -i -X PATCH [RESTHEART-URL]/users/foo \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "betterSecret"
}'

HTTPie

http PATCH [RESTHEART-URL]/users/foo \
  Content-Type:application/json \
  password="betterSecret"

JavaScript

const username = 'your-username';
const password = 'your-password';
const credentials = btoa(`${username}:${password}`);

fetch('[RESTHEART-URL]/users/foo', {
    method: 'PATCH',
    headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "password": "betterSecret"
    })
})
.then(response => {
    if (response.ok) {
        console.log('User updated successfully');
    } else {
        console.error('Failed to update user:', response.status);
    }
})
.catch(error => console.error('Error:', error));

Delete a user

cURL

curl -i -X DELETE [RESTHEART-URL]/users/foo -H "Authorization: Basic [BASIC-AUTH]" \

HTTPie

http DELETE [RESTHEART-URL]/users/foo Authorization:"Basic [BASIC-AUTH]"

JavaScript

const username = 'your-username';
const password = 'your-password';
const credentials = btoa(`${username}:${password}`);

fetch('[RESTHEART-URL]/users/foo', {
    method: 'DELETE',
    headers: {
        'Authorization': `Basic ${credentials}`
    }
})
.then(response => {
    if (response.ok) {
        console.log('User deleted successfully');
    } else {
        console.error('Failed to delete user:', response.status);
    }
})
.catch(error => console.error('Error:', error));

Managing Permissions

For detailed information about creating and managing permissions, including advanced permission features like predicates, MongoDB-specific permissions, filters, and complete examples, see Permission Management.

Quick Example: Create a Basic Permission

cURL
curl -i -X POST [RESTHEART-URL]/acl \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{
  "predicate": "path-prefix[/inventory] and method[GET]",
  "roles": [ "user" ],
  "priority": 1
}'
HTTPie
http POST [RESTHEART-URL]/acl \
  Authorization:"Basic [BASIC-AUTH]" \
  Content-Type:application/json \
  predicate="path-prefix[/inventory] and method[GET]" \
  roles:='["user"]' \
  priority:=1
JavaScript
const username = 'your-username';
const password = 'your-password';
const credentials = btoa(`${username}:${password}`);

fetch('[RESTHEART-URL]/acl', {
    method: 'POST',
    headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "predicate": "path-prefix[/inventory] and method[GET]",
        "roles": [ "user" ],
        "priority": 1
    })
})
.then(response => {
    if (response.ok) {
        console.log('ACL permission created successfully');
    } else {
        console.error('Failed to create ACL permission:', response.status);
    }
})
.catch(error => console.error('Error:', error));
Tip
 For comprehensive permission documentation including advanced features like readFilter, writeFilter, mergeRequest, projectResponse, predicates, and complete examples, see Permission Management.