User-defined roles

User-defined roles provide configurable, domain-specific security rules. They are the core schema for attribute-based access control. Roles are created with the CreateRole function, and have the following structure:

Field name Value type Description



The role’s name.





Optional. One or more membership configuration objects.

User-defined roles can only be managed with an admin key.

Privilege configuration object

A privilege configuration object defines, for a given resource, what actions are permitted.

Field name Value type Description



A reference to a collection, index, set, or user-defined function.



An object containing key-value pairs, where the keys are action names, and the values are either a boolean value to indicate whether access is permitted, or a predicate function that can compute whether access is permitted.

The available actions are:

  • create: permits the create of new documents, collections, or set.

  • delete: permits the deletion of existing documents, collections, or sets.

  • read: permits the reading of documents, collections, sets, or indexes.

  • write: permits writing to existing documents within a collection.

  • history_read: permits reading historical versions of a document, collection, or set.

  • history_write: permits inserting events into the history for an existing document or set.

  • unrestricted_read: permits the reading of an index without considering any other read permissions.

  • call: permits the calling of user-defined functions.

When configuring read access to an index, both the read and unrestricted_read actions are permitted. The read action grants access to the index’s data. However, an additional read permission check is performed before allowing access to the indexed document, which filters out references that the user cannot read. The unrestricted_read action disables the additional check, returning all of the documents associated with the index.

An action’s value can be a boolean, to indicate whether the action is permitted or not, or a read-only lambda predicate function. Lambda predicate functions must be created using a query, using the same format that the CreateFunction function accepts. The predicate function takes different parameters depending on the configured action. Predicates must return a boolean value where true grants the action, and false denies it.

The parameters to a predicate function are:

Action Argument(s) Description



An object containing the new document’s data.



The reference to the document to be deleted.


Reference, or index terms

A reference to the document to be read, or one or more terms to be matched against the target index.


Object, Object

Two objects, one containing the original document data, and the second containing the new document data to be written.



The reference to the document to be read.


Reference, Timestamp, String, Object

The reference to the document to be written, the timestamp to write to (which may create or update an event depending on existence of a matching timestamp), the action string, and an object containing the new document data.


Index terms

The terms matched against the target index.



The parameters that are to be passed to the user-defined function.

Membership configuration object

A membership configuration object dynamically defines which authenticated resources are members of a given role. Tokens is covered in the next section.

Field name Value type Description



A reference to a collection in which its documents are members of the configured role.



Optional. A read-only lambda predicate function that takes the reference of the authenticated resource and returns a boolean value that indicates whether the referenced resource is a member of the configured role.


Tokens, like keys, allow direct access to FaunaDB by application users. Their use is optional. Where keys provide database-level access, each token has an associated document. Requests made with a token apply resource-level permission checks based on its document. When a document is a member of a user-defined role, that role is used to evaluate the user’s permissions.

Both server and client keys can generate tokens. Token generation with a client key requires a password. The password is optional when using a server key, but is verified if provided.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!

Thank you for your feedback!