Key

Description

The Key collection is a native collection of key documents. Documents in this collection have an immutable, Fauna-defined structure. Keys are tied to a database and allow access to its contents. Database owners or administrators typically use keys to manage database structure and contents with few restrictions. Keys are frequently used for background tasks that automate routine database procedures.

The Key.create() method can specify an optional database field. If no database is supplied, the Key.create() grants access to the current database.

Unlike Token documents, a Key document has no associated credential, so there is no identity. The lack of a credential means that keys grant anonymous-based access to a database. Any person or process with a Fauna key secret can access the database associated with the key.

The access permissions that a key grants depend on the role field supplied by Key.create(). A key can attach to user-defined roles for attribute-based access control (ABAC) or to the Fauna built-in roles. A user-defined Role document has a privileges array specifying one or more resources and the actions permitted on that resource. The built-in roles have the following built-in privileges:

Built-in role Description

admin

Used to manage the associated database, including the database access providers, child databases, documents, functions, indexes, keys, tokens, and user-defined roles. Protect key secrets with administrative privileges in the same way as a root password.

When a user-defined function (UDF) has the admin role, calling that function causes it to be executed with all available privileges.

server

Equivalent to the admin role with some exceptions. User-defined roles, child databases, keys, tokens, and their associated documents cannot be directly managed with the server role. Keys with this privilege should be well protected.

The server role has the create, write, and call permissions on User-defined functions (UDFs). The server role can assign any role to a UDF, including the admin role.

server-readonly

Provides read-only access to all data in the database that they’re assigned to. Because they grant unrestricted read access, they should be well protected and only used in trusted or server-side environments.

client

Deprecated. Do not use.

Reading or writing key documents requires the admin key or equivalent permissions from a user-defined role.

See the Key document definition.

Manage key secrets

When Key.create() is called, Fauna returns a key document that includes the key secret field. This is a password-equivalent field. The caller must retrieve the secret from the result and store it. Fauna cannot recover a secret that is discarded or lost.

Follow these guidelines:

Never embed the admin key secrets into applications.
Share admin key secrets only with individuals that need unrestricted database access.
Consider creating a user-defined administrative role and applying membership to user documents instead of using admin key secrets.
Ensure that keys that attach to user-defined roles have the minimum level of access needed to do the required actions.

Static methods

Method Description

Method	Description
`Key.all()`	Get the set of all Key objects.
`Key.byId()`	Get a key by ID.
`Key.create()`	Create a key.
`Key.firstWhere()`	Get the first key matching a predicate function.
`Key.where()`	Get keys matching a predicate function.

Key.all()

Get the set of all Key objects.

Key.byId()

Get a key by ID.

Key.create()

Create a key.

Key.firstWhere()

Get the first key matching a predicate function.

Key.where()

Get keys matching a predicate function.