Fauna key system

Access to the Fauna API uses secrets that correspond to access keys, which authenticate connections as having particular permissions. The access key system applies both to administrator- and server-level connections, as well as to object- and user-level connections.

Keys are defined as documents within the keys collection. Like databases, keys exist within the system-global root database context.

Keys are tied to a specific database and allow access to its contents. If no database is specified, the key grants access to the database in which it was created. The level of access a key provides depends on its role.

You must copy the key’s secret out of the key when it is first created and store it securely. Only a BCrypt hash of the key is stored on disk. It is impossible to recover the key’s secret if it is discarded.

This page includes the following topics:

Fields

Field name Value type Description

role

String

The key’s role. Either admin, server, server-readonly, client, or one or more user-defined roles.

Client keys and roles, and public permissions are deprecated as of the 2.12.0 release. You should use the Attribute-based access control (ABAC) system instead,

See Deprecations for more details.

secret

String

The key’s authentication secret. Only present on creation.

hashed_secret

String

The key’s hashed authentication secret.

priority

Number

A priority between 1 and 500, inclusive. Defaults to 1.

The priority option is deprecated as of release 2.10.0. You should avoid specifying priority. In some future Fauna release, priority will be removed. See Deprecations for more details.

database

Database ref

The database associated with this key. Optional.

data

Object

A JSON object. Optional.
Once you have key, you can use its secret to authenticate GraphQL queries.

Beginning with Fauna 2.11.0, the Fauna access control logic has been changed to use attribute-based access control (ABAC) roles, or the key-based permission system, but never both.

If a resource is a member of an ABAC role, the ABAC role specifies all privileges for that resource. Otherwise, the key-based permission system determines whether read/write/execute privileges are enabled.

For example, when an ABAC role includes a user-defined function as a member, that function cannot be called unless the ABAC privileges permit the call action.

Access keys

Keys belong to one of four built-in roles, either admin, server, server-readonly, or client, or to one or more used-defined roles.

Admin keys

Keys with the admin role are used for managing databases, keys, and user-defined roles. An admin key can be used to create and destroy databases and keys. They should be very well protected.

Admin keys for Fauna accounts are managed in the Dashboard.

Server keys

Keys with the server role bypass all permission checks within the database they’re assigned to. Because they provide unrestricted access, they should be well protected and only used in trusted or server-side environments.

Server read-only keys

Keys with the server-readonly role allow read-only access to all data within the database that they are assigned to. Because they provide unrestricted read access, they should be well protected and only used in trusted or server-side environments.

Client keys

Keys with the client role are restricted to actions and resources that are specifically marked with the public permission. Because their access is controlled, they are suitable for embedding in untrusted environments, such as mobile clients.

Typically they are used as part of an application’s user authentication flow, or to access public data, such as an application’s logged-out view.

Client keys and roles, and public permissions are deprecated as of the 2.12.0 release. You should use the Attribute-based access control (ABAC) system instead,

See Deprecations for more details.

Scoped keys

There are several situations where you might want to impersonate access to a database, because regular access is more difficult or you are lacking information. For example:

  • You have a reporting tool that needs to gather information from all of your child databases. To access a child database, you would typically need to use a secret associated with each child database. With hundreds or thousands of child databases, managing those secrets is challenging.

  • Your application performs queries on behalf of users, and you need to test that functionality and/or access controls are working correctly. However, you don’t have access to any user’s password in order to call Login.

  • Similarly, your applications provides different functionality for users with differing roles, and you need to test the functionality and access controls.

To facilitate these use cases, Fauna accepts a scoped key. A scoped key allows you to use a secret that you already possess to impersonate access to Fauna in several ways. However, it is not possible to use a scoped key to gain additional privileges.

A scoped key is formed from the secret of a key that you already possess, plus some additional information that provides three impersonation alternatives:

  1. secret[:child_database]:role

    Where:

    • secret is the key’s secret. An admin key is required to access a child database.

    • child_database is the name of a child database (optional). When specified, the secret for an admin key must be used. When not specified, the secret from an admin or server key can be used.

    • role is the name of a system role to use, one of admin, server, server-readonly, or client.

    This kind of scoped key would typically be used to impersonate access to a child database.

    For example: fnACysRJGIACAHiL_5f0UxHlPFIZgq876ptMNJ72:posts:admin

    Provided that the secret belong to an admin key, this scoped key provides full access to the child database called posts.

  2. secret[:child_database]:@doc/collection/id

    Where:

    • secret is the key’s secret. An admin key is required to access a child database.

    • child_database is the name of a child database (optional). When specified, the secret for an admin key must be used. When not specified, the secret from an admin or server key can be used.

    • collection is the name of a collection in the current database, or if child_database is specified, in the child database.

    • id is the reference id for the document to authorize as.

    This kind of scoped key would be used to impersonate a specific user.

    For example: fnACysRJGIACAHiL_5f0UxHlPFIZgq876ptMNJ72:@doc/users/1234

    This scoped key would have the same privileges as the authenticated Ref(Collection("users"), 1234) document.

  3. secret[:child_database]:@role/name

    Where:

    • secret is the key’s secret. An admin key is required to access a child database.

    • child_database is the name of a child database (optional). When specified, the secret for an admin key must be used. When not specified, the secret from an admin or server key can be used.

    • name is the name of an ABAC role to authorize as.

    This kind of scoped key would be used to impersonate any user having the privileges of the specified role.

    For example: fnACysRJGIACAHiL_5f0UxHlPFIZgq876ptMNJ72:@role/developers

    This scoped key would have the same privileges as any member document with the developers role.

Next steps

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!