Rule Templates & Examples
On this page
- Apply When Expressions
- The User Is the Document Owner
- An Array Field Contains the User's ID
- The User Has An Email Address
- The User Has A Specific Email Address
- A Field Contains the User's Email Address
- An Array Field Contains the User's Email Address
- A Field Satisfies a Complex Condition
- CRUD Permissions
- The Role Can Read All Fields but Cannot Write
- The Role Can Read & Write All Fields
- The Role Can Read All Fields & Write to Specific Fields
- The Role Can Read & Write All Fields but Cannot Insert New Documents
- The Role Cannot Write to Specific Fields
- Advanced Role Patterns
- Insert-Only Roles
- Field-level Permissions for Embedded Documents
The content in this section only applies when Atlas Device Sync is not enabled. For information about configuring permissions when using Sync, see Sync Rules and Permissions.
Apply When Expressions
Atlas App Services determines if a role applies to a given document by evaluating the Apply When expression that you define for each role.
This section contains examples of Apply When expressions for common scenarios.
To apply an expression to a role, find the scenario that most closely matches
your use case and then copy and paste the provided template into the role. You
may need to modify placeholder values (denoted by <angle brackets>
) in the
template to match your collection or otherwise adapt the template to fit your
needs.
You can also use the Apply When expressions on this page for external services and sync rules.
The User Is the Document Owner
This expression evaluates to true
if the active user's unique id
value matches the value of the specified field.
{ "<Owner ID Field>": "%%user.id" }
An Array Field Contains the User's ID
This expression evaluates to true
if the active user's unique id
value matches one or more values in the specified array field.
{ "<Array Field>": "%%user.id" }
The User Has An Email Address
This expression evaluates to true
if the active user has any email
address listed in their internal user object.
{ "%%user.data.email": { "%exists": true } }
The User Has A Specific Email Address
This expression evaluates to true
if the active user's email address
matches the specified email address.
{ "%%user.data.email": "<Email Address>" }
A Field Contains the User's Email Address
This expression evaluates to true
if the active user's email address
matches the value of the specified field.
{ "%%root.email": "%%user.data.email" }
An Array Field Contains the User's Email Address
This expression evaluates to true
if the active user's email address
matches one or more string values in the specified array field.
{ "<Array Field>": "%%user.data.email" }
A Field Satisfies a Complex Condition
This expression evaluates to true
if the Function isAuthorizedUser
returns true
when passed the
active user's id value.
You can call any Atlas App Services Function from a JSON expression using the
%function
operator.
{ "%%true": { "%function": { "name": "isAuthorizedUser", "arguments": ["%%user.id"] } } }
CRUD Permissions
Atlas App Services uses a role's permissions configuration to determine if the active user can insert or delete a document as well as which fields in the document they can read and write.
This section contains templates that define role permissions for
common scenarios. To apply a set of permissions to a role, find the
scenario that most closely matches your use case. Update the role's
permissions table to match the provided screenshot or copy and paste the
provided template into the collection's advanced mode configuration. Make sure that you modify
any placeholder values (denoted by <angle brackets>
) in the template
to match your needs.
The Role Can Read All Fields but Cannot Write
To allow a role to read any field, set the document-level read
field
to true
.
![]() |
|
The Role Can Read & Write All Fields
To allow a role to read or write any field, set the document-level
write
field to true
. Document-level writes require read
permission, so the role will be able to read all fields.
![]() |
|
The Role Can Read All Fields & Write to Specific Fields
To allow a role to read all fields, set the document-level read
field to true
. To specify a field that the role can write to, set
the write
field to true
in the field's configuration document,
which is embedded in the fields
document.
![]() |
|
The Role Can Read & Write All Fields but Cannot Insert New Documents
To allow a role to read or write any field, set the document-level
write
field to true
. Document-level writes require read
permission, so the role will be able to read all fields.
To prevent the role from inserting new documents, set the document-level
insert
field to false
.
![]() ![]() |
|
The Role Cannot Write to Specific Fields
To allow a role to write to any field except for those you specify, set
the corresponding field-level write
fields to false
in the
fields
document and set the additional_fields.write
field to
true
.
![]() |
|
Advanced Role Patterns
The use cases described in this section require you to use advanced functionality that is not supported by the default collection rules editor in the Atlas App Services UI. To use this template, convert to advanced mode or import a collection rule configuration with Realm CLI.
Insert-Only Roles
To allow a role to insert new documents but otherwise prevent them from reading
or modifying any data, set insert
to true
and set the value of
document-level write
to a rule expression that
evaluates to true
only if the document didn't exist prior to the operation.
{ "name": "insertOnly", "apply_when": <JSON Expression>, "delete": false, "insert": true, "write": { "%%prevRoot": { "%exists": false } }, "additional_fields": {} }
You must specify a JSON expression for write
to prevent users
from reading data. To insert a document a role must also have write
permission for all fields in the document; however, setting write
directly to true
would also give the role read permission. The
JSON expression ensures that the role only has read permission for
the initial document insert.
Field-level Permissions for Embedded Documents
To allow a role to read or write some but not all fields of an embedded
document, add embedded documents that match the path of the embedded
field to the fields
document.
{ "name": "canReadEmbeddedField", "apply_when": {}, "delete": true, "insert": true, "fields": { "someEmbeddedDocument": { "fields": { "someEmbeddedField": { "read": true, "write": true } } } }, "additional_fields": {} }
Atlas App Services applies any read
and write
permissions defined for a
given field to all embedded fields that the field contains regardless
of any permissions defined for those fields.