User Management
🔧 Configuration
⚡ 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:
-
Sign up at cloud.restheart.com
-
Create a free API service
-
Set up your root user following the Root User Setup guide
-
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
|
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.
|
Tip
|
Watch Managing users with practical examples |