Keys

Reference: Key

A key is a type of authentication secret used for anonymous access to a Fauna database. Unlike tokens, keys are not associated with an identity.

You can use keys for system processes and applications that don’t require identity-based authentication.

You can also use a key to bootstrap a Fauna-based end-user authentication system. The key can provide the minimum access required for end users to sign up and log in to your application.

Key role

Each key is assigned a single role. The role can be built-in or user-defined. The role determines the key secret’s privileges, which control data access.

See Roles

Scope

Keys are scoped to a specific database or an account’s top-level context.

If a key is scoped to a database, you can use scoped keys to access the database’s child databases and their descendants. You can’t use a key to access parent or peer databases.

If a key is scoped to an account’s top-level context, you can use scoped keys to access all databases in the account.

Key collection

Fauna stores keys scoped to a database as documents in the database’s Key system collection. You can use Key methods to access Key collection documents in FQL.

Keys scoped to an account’s top-level context are not stored as documents.

See Key FQL docs

Create and manage keys

You can create and manage keys using:

For example, the following FQL query creates a key with the built-in admin role:

Key.create({
  // Creates a key with the built-in `admin` role.
  role: "admin"
})

The result includes the key’s secret, which you can use to authenticate with Fauna. A key’s secret is shown once — when you create the key.

{
  id: "402596308273070146",
  coll: Key,
  ts: Time("2099-07-05T18:36:49.090Z"),
  // Key's secret
  secret: "fn...",
  role: "admin"
}

You can use the same secret to authenticate multiple Fauna requests. A secret remains valid until it expires or is deleted.

Update a key’s role

You can update a key’s role using the key.update() method:

Key.byId("402596308273070146")?.update({
  // Changes the key's role to the built-in `server` role.
  role: "server"
})

Fauna checks a key’s role and related privileges at query time for every query.

Reference: key.update()

Key expiration

A Key document can include an optional ttl (time-to-live) field that contains the key’s expiration timestamp:

Key.create({
  role: "admin",
  // Creates a key that expires in one day.
  ttl: Time.now().add(1, "days")
})
{
  id: "402599582390812736",
  coll: Key,
  ts: Time("2099-07-05T19:28:51.520Z"),
  // The `Key` document includes a `ttl` timestamp.
  ttl: Time("2099-07-06T19:28:51.499944Z"),
  role: "admin",
  secret: "fn..."
}

After the ttl timestamp passes, Fauna permanently deletes the key and its secret. You can’t use an expired key’s secret to authenticate requests.

A Key document without a ttl does not expire and persists until deleted.

Recover a lost key secret

You can’t recover or regenerate a lost key secret. After creation, Key documents don’t include the key’s secret. Instead, delete the key and create a new one.

Scoped keys

A scoped key lets you use a parent database’s admin key to send query requests to its child databases or descendants. This provides a secure way to:

  • Access child databases without managing multiple keys

  • Test user-defined roles and end-user privileges

  • Impersonate other secrets you could create with the existing admin key

You create a scoped key by appending parameters to an existing key’s secret. The existing key must have the built-in admin role. For example:

  • fn…​:childDB:admin creates a scoped key with the admin role for the childDB child database.

  • fn…​:test/performance:server creates a scoped key with the server role for the performance database within the test child database.

The following section outlines the syntax and examples for scoped key types.

Impersonate a built-in role

You typically use this type of scoped key to impersonate access to a child database.

Syntax

<KEY_SECRET>[:<CHILD_DATABASE>]:<ROLE>

Example

// Scoped key that impersonates the `server` role
// for the database scoped to the secret.
fn...:server

// Scoped key that impersonates the `admin` role for
// the `child_db` child database.
fn...:child_db:admin

// Scoped key that impersonates the `admin` role for
// the `grand_child_db` database, nested under `child_db`.
fn...:child_db/grand_child_db:admin

Parameters

Parameter Required Description

<KEY_SECRET>

true

Key secret.

<CHILD_DATABASE>

Name of a child database. To access a nested child database, separate the database names by /. For example, use test/performance to access the performance database within the test child database.

<ROLE>

true

Built-in role. Accepts admin, server, or server-readonly.

Impersonate an end user

You typically use this type of scoped key to impersonate a token for a specific end user or another identity document.

Impersonated tokens can be assigned multiple user-defined roles through role membership. You can use the scoped key to test role membership for tokens or role-related predicates.

Syntax

<KEY_SECRET>[:<CHILD_DATABASE>]:@doc/<COLLECTION>/<DOCUMENT_ID>

Example

// Scoped key that impersonates a token with a `Customer`
// identity document in the database scoped to the secret.
fn...:@doc/Customer/123

// Scoped key that impersonates a token with a `Manager`
// identity document in the `child_db` child database.
fn...:child_db:@doc/Manager/456

// Scoped key that impersonates a token with a `Owner`
// identity document in the `grand_child_db` database,
// nested under `child_db`.
fn...:child_db/grand_child_db:@doc/Owner/789

Parameters

Parameter Required Description

<KEY_SECRET>

true

Key secret.

<CHILD_DATABASE>

Name of a child database. To access a nested child database, separate the database names by /. For example, use test/performance to access the performance database within the test child database.

<COLLECTION>

true

User-defined collection in the database. If a <CHILD_DATABASE> is provided, this is a collection in the child database.

The collection typically contains documents that represent an end user or similar identity. Fauna assigns roles to the impersonated token based on this collection and the role’s membership property.

<DOCUMENT_ID>

true

Document ID for the impersonated token’s identity document. The identity document must be in the <COLLECTION>.

Impersonate a user-defined role

You typically use this type of scoped key to impersonate a user-defined role.

Syntax

<KEY_SECRET>[:<CHILD_DATABASE>]:@role/<ROLE>

Example

// Scoped key that impersonates the user-defined `customer` role
// for the database scoped to the secret.
fn...:@role/customer

// Scoped key that impersonates the `manager` role
// for the `child_db` child database.
fn...:child_db:@role/manager

// Scoped key that impersonates the `owner` role
// for the `grand_child_db` database, nested
// under `child_db`.
fn...:child_db/grand_child_db:@role/owner

Parameters

Parameter Required Description

<KEY_SECRET>

true

Key secret.

<CHILD_DATABASE>

Name of a child database. To access a nested child database, separate the database names by /. For example, use test/performance to access the performance database within the test child database.

<ROLE>

true

User-defined role to impersonate. If using a child database, the role must exist in the child database.

Dashboard-created keys

The Fauna Dashboard automatically creates a temporary key when you:

  • Log in to the Dashboard. This key has the built-in admin role.

  • Use the Dashboard Shell’s authentication drop-down to run a query using a role other than Admin.

    Run a query as a role

Dashboard-created keys have a 15-minute ttl (time-to-live) and are scoped to their specific database. Related Key documents include a data field with related metadata:

{
  id: "414467050449141793",
  coll: Key,
  ts: Time("2099-11-13T19:17:11.020Z"),
  ttl: Time("2099-11-13T19:32:09.915Z"),
  data: {
    name: "System-generated dashboard key"
  },
  role: "admin"
}

The Dashboard surfaces this metadata in the database’s Keys tab on the Explorer page.

Key’s tab in the Fauna Dashboard

\