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

Note

The content in this section only applies when Atlas Device Sync is not enabled. For information about configuring permissions when using Sync, see Sync Permissions Overview.

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.

Note

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.

Note

You can call any Atlas Function from a JSON expression using the %function operator.

{
  "%%true": {
    "%function": {
      "name": "isAuthorizedUser",
      "arguments": ["%%user.id"]
    }
  }
}

CRUD Permissions

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.

A role with permission to read all document fields

{
  "name": "<Role Name>",
  "apply_when": <JSON Expression>,
  "insert": <boolean>,
  "delete": <boolean>,
  "read": 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.

A role with permission to read and write all document fields

{
  "name": "<Role Name>",
  "apply_when": <JSON Expression>,
  "insert": <boolean>,
  "delete": <boolean>,
  "write": true,
}

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.

A role with permission to write to specific fields

{
  "name": "<Role Name>",
  "apply_when": <JSON Expression>,
  "insert": <boolean>,
  "delete": <boolean>,
  "read": true,
  "fields": {
    "<Field Name>": { "write": true },
    ...
  }
}

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.

A role that lacks permission to insert new documents

{
  "name": "<Role Name>",
  "apply_when": <JSON Expression>,
  "insert": false,
  "delete": <boolean>,
  "write": true,
}

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.

A role with permission to write to some but not all fields

{
  "name": "<Role Name>",
  "apply_when": <JSON Expression>,
  "insert": <boolean>,
  "delete": <boolean>,
  "read": true,
  "fields": {
    "<Field Name>": {
      "read": true,
      "write": false
    },
    ...
  },
  "additional_fields": { "write": 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 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": {}
}

Note

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": {}
}

Note

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.

← Rule Expressions Define Roles And Permissions →