v9 (current) v8
Edit Page

Managing Users

Cloud

The User Management section of the RESTHeart Cloud UI lets you create, search, edit, and delete the users that authenticate against your service via Basic Auth or Token Auth. These users are stored in the RESTHeart users collection and are entirely separate from your RESTHeart Cloud account credentials.

Navigation path: Service → Users

How Users Work

Each user document stored in the users collection represents an identity that can authenticate against your RESTHeart service. When a client sends a request with Authorization: Basic <base64(username:password)>, RESTHeart looks up the user by _id, verifies the password hash, and grants the roles defined on that document.

The roles assigned to a user are referenced by the ACL rules defined in the Permissions section. A user with no matching ACL rules is effectively read-only or denied, depending on your permission configuration.

Collection Path by Plan

Plan Users collection path

Free / Shared

/users

Dedicated

/restheart/users

The UI abstracts this difference — you always navigate to Service → Users regardless of plan.

User Document Structure

{
  "_id": "alice",
  "password": "plaintextOnWrite_hashedByServer",
  "roles": ["user", "editor"]
}
Field Required Description

_id

Yes

The username. Used as the document identifier and as the value clients provide in the Authorization header. Must be unique.

password

Yes (on create)

The plaintext password sent by the client. RESTHeart automatically hashes it with bcrypt before storing it. On edit, leave this field blank to keep the existing password.

roles

Yes

Array of role name strings. These roles are matched against the ACL rules in the Permissions section. You can define any role names you like; the only built-in role with special meaning is admin (configured as the root role by default).
Important
 Passwords are never stored in plaintext. The UI sends the password you type to RESTHeart, which immediately applies bcrypt hashing before persisting the document. You cannot retrieve a stored password — only reset it.

Listing Users

The user list is fetched via GET /users?page=…​&pagesize=…​ and displayed in a paginated, searchable table. Each row shows the _id, the assigned roles, and action buttons.

Searching and Filtering

Use the Search box to filter users by a MongoDB query expression, for example:

{ "roles": "admin" }

or

{ "_id": { "$regex": "^alice", "$options": "i" } }

The filter is sent as the filter query parameter. A Sort expression (JSON object) can also be applied, mapping to the sort query parameter.

Pagination

Use the Previous / Next buttons to page through results. The page size is configurable via a dropdown in the toolbar.

Creating a User

  1. Click New User.

  2. Fill in the form:

    • Username (_id) — the identifier used for authentication.

    • Password — the plaintext password; RESTHeart hashes it automatically.

    • Roles — add one or more role names. Click Add Role to insert additional role fields.

  3. Click Save. The UI submits POST /users with the document body.

Tip
 Use descriptive role names that reflect your application’s permission model (e.g. reader, writer, moderator, admin). These names are referenced in your ACL rules.

Show/Hide Password

The password field is masked by default. Click the eye icon to toggle visibility while typing.

Editing a User

  1. Click Edit on a user row to expand the inline accordion form.

  2. The form is pre-populated with the current _id and roles. The password field is blank — leave it blank to keep the existing password, or type a new value to reset it.

  3. Modify the roles or set a new password, then click Save. The UI issues PATCH /users/<id> with only the changed fields.

Note
 The _id (username) is read-only after creation. To rename a user, delete the existing document and create a new one.

Deleting a User

Click Delete on a user row. A confirmation dialog appears before the DELETE /users/<id> request is issued. Deleting a user immediately revokes all active sessions for that identity.

JWT Claims

A JWT issued by your service carries, besides the identity and the roles, whichever fields of the user document you choose to expose as claims. Anything not in that list is invisible to code reading the token — including ACL permissions and Guards conditions, for a user authenticating with a token rather than with a password.

Navigation path: Service → Users → the wrench button → JWT Claims

  1. Type a field name and press Enter, or click +.

  2. Nested fields use / as the separator: consents/tos/version selects that nested value and rebuilds the nesting inside the token.

  3. Click Save Claims.

The changes apply to newly issued tokens. Users already signed in keep their current claims until they obtain a new one.

What You Cannot Expose

A JWT payload is base64, not encrypted: any client holding the token can read every claim in it. Credentials are therefore refused at issuance whatever the list says — the password field and the one-shot verification and password-reset tokens. The dialog flags them as you type, but the server is what enforces it.

Claims That Are Always There

RESTHeart Cloud adds a few claims of its own to every token — among them the one identifying the node that issued it, which is checked on every subsequent request. They are not removable: a service able to drop them would lock itself out.

Choosing What to Expose

Add a field when something needs to read it without a database lookup — a permission, a guard condition, or your frontend. Every claim makes the token larger and is sent with every request, so a list that mirrors the whole user document is the wrong shape.

API Reference

Operation Endpoint

List users

GET /users?page=…​&pagesize=…​&filter=…​&sort=…​

Create user

POST /users

Update user

PATCH /users/<id>

Delete user

DELETE /users/<id>

On Dedicated plans replace /users with /restheart/users in all paths above.

Note
 If your service also has Sign-up Management enabled, the /users resource additionally enforces a restriction limiting your own end users to self-service profile.* edits (RESTHeart 9.6.0+). This User Management UI is unaffected and continues to create, edit (including roles), and delete users normally — RESTHeart Cloud manages your service on your behalf using a role that’s exempt from that restriction. See Sign-up Management for details.

Built-in and Custom Roles

RESTHeart Cloud does not enforce a fixed role hierarchy beyond the root role (admin by default). You are free to define any roles that fit your application:

Example role Typical use

admin

Full administrative access. Matches the root ACL rule (rootCanDoEverything).

user

Standard authenticated user with access scoped by ACL rules.

reader

Read-only access to specific collections.

writer

Read/write access to specific collections.

(any custom name)

Define roles that match your application domain — e.g. moderator, analyst, service-account.

The roles defined here are the same roles referenced in the roles array of your ACL permission rules.

Security Considerations

  • Choose strong, unique passwords for all users.

  • Follow the principle of least privilege: assign only the roles a user genuinely needs.

  • Regularly audit the user list and remove accounts that are no longer required.

  • The admin role grants full access by default. Limit its assignment to trusted administrators.

  • Passwords are hashed with bcrypt — there is no way to retrieve a stored password. Use the edit form to reset a forgotten password.