Docs Menu

Docs Home → Atlas App Services

Data Access Role 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

"Apply When" Expressions

Atlas App Services determines if a role applies by evaluating the "apply when" expression that you define for each role.

This section contains examples of "apply when" expressions for common scenarios where you're not using Device Sync. For guidance on common Device Sync scenarios, see the Device Sync Permissions Guide.

To add 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.

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" refers to whatever field in your schema represents a relationship with a user object.

{
  "<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 roles for common scenarios. To apply a set of permissions to a role, find the scenario that most closely matches your use case. Update the Field Permissions, Document Permissions, and/or 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 and write field to false.

A role with permission to read all document fields
{
  "name": "<Role Name>",
  "apply_when": {<JSON Expression>},
  "document_filters": {<JSON Expression>},
  "insert": <boolean>,
  "delete": <boolean>,
  "read": true,
  "write": false
}

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>},
  "document_filters": {<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 and the write field to false. 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>},
  "document_filters": {<JSON Expression>},
  "insert": <boolean>,
  "delete": <boolean>,
  "read": true,
  "write": false,
  "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>},
  "document_filters": {<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 document-level read field to true. Set the corresponding field-level write fields to false and read fields to true in the fields document. Lastly, 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>},
  "document_filters": {<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 App Services 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.

← Configure Advanced Rules
Secure Your App →

On this page