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 system collection

Fauna stores keys as documents in the Key system collection. You can use Key methods to access Key collection documents in FQL.

See Key FQL docs

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

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 update() method:

Key.byId("<KEY_DOCUMENT_ID>")?.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: update()

Manage keys with the Fauna CLI

You can create, list, and delete keys using related Fauna CLI commands. However, you can’t use the CLI to create a key with a user-defined role.

Reference: Fauna CLI commands

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.

Scope

Key documents are scoped to a single database. You can use scoped keys to access this database’s child databases and their descendants. You can’t use a key to access parent or peer databases.

Scoped keys

A scoped key lets you use an existing key to impersonate database access as another secret or end user — without granting additional privileges.

You create a scoped key by appending parameters to an existing key’s secret. The existing key must have the built-in admin role. A scoped key lets you impersonate secrets you could otherwise create with the existing key.

This is more convenient and secure than creating and managing multiple separate keys.

You can use a scoped key to:

  • Access child databases without creating and managing multiple keys

  • Verify the privileges of a user-defined role

  • Test the privileges of a specific end user without using their actual password

You can’t use a scoped key to gain more privileges than the existing key.

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 an `admin` key for
// the `childDB` child database.
fn...:childDB:admin

Parameters

Parameter Required Description

<KEY_SECRET>

Yes

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>

Yes

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.
fn...:@doc/Customer/12345

Parameters

Parameter Required Description

<KEY_SECRET>

Yes

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>

Yes

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>

Yes

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 single user-defined role.

Syntax

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

Example

// Scoped key that impersonates the user-defined `customer` role.
fn...:@role/customer

Parameters

Parameter Required Description

<KEY_SECRET>

Yes

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>

Yes

User-defined role to impersonate.

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!