RESTHeart - User Management

User Management

🔧 Configuration

Client Type

Instance URL

Username

Password

Sets localhost:8080 with admin:secret

Values are saved in your browser

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.

Before running the example requests

The following examples assume RESTHeart running on the localhost with the default configuration: the database restheart is bound to / and the user admin exists with default password secret.

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

<span class="mr-3 text-muted"><strong>Request</strong></span>

</div>

cURL

curl -i -u [BASIC-AUTH] -X GET [INSTANCE-URL]/users

HTTPie

http -a [BASIC-AUTH] GET [INSTANCE-URL]/users

JavaScript

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

fetch('[INSTANCE-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));

Response

[
  {
    "_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

<span class="mr-3 text-muted"><strong>Request</strong></span>

</div>

cURL

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

HTTPie

http -a [BASIC-AUTH] POST [INSTANCE-URL]/users \
  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('[INSTANCE-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

<span class="mr-3 text-muted"><strong>Request</strong></span>

</div>

cURL

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

HTTPie

http -a [BASIC-AUTH] PATCH [INSTANCE-URL]/users/foo \
  Content-Type:application/json \
  password="betterSecret"

JavaScript

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

fetch('[INSTANCE-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

<span class="mr-3 text-muted"><strong>Request</strong></span>

</div>

cURL

curl -i -u [BASIC-AUTH] -X DELETE [INSTANCE-URL]/users/foo

HTTPie

http -a [BASIC-AUTH] DELETE [INSTANCE-URL]/users/foo

JavaScript

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

fetch('[INSTANCE-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));

Create an ACL document

<span class="mr-3 text-muted"><strong>Request</strong></span>

</div>

cURL

curl -i -u [BASIC-AUTH] -X POST [INSTANCE-URL]/acl \
  -H "Content-Type: application/json" \
  -d '{
  "predicate": "path-prefix[/inventory] and method[GET]",
  "roles": [ "user" ],
  "priority": 1
}'

HTTPie

http -a [BASIC-AUTH] POST [INSTANCE-URL]/acl \
  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('[INSTANCE-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	Check Format of permission for more information on ACL permissions.

Tip	Watch Managing users with practical examples