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.
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() |
|---|
Manage keys with the Fauna CLI
You can create, list, and delete keys using related Fauna CLI commands. 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.
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:admincreates a scoped key with theadminrole for thechildDBchild database. -
fn…:test/performance:servercreates a scoped key with theserverrole for theperformancedatabase within thetestchild 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.
Example
// Scoped key that impersonates an `admin` key for
// the `childDB` child database.
fn...:childDB:adminParameters
| Parameter | Required | Description |
|---|---|---|
|
Yes |
Key secret. |
|
Name of a child database. To access a nested child database, separate the
database names by |
|
|
Yes |
Built-in role. Accepts |
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.
Example
// Scoped key that impersonates a token with a `Customer`
// identity document.
fn...:@doc/Customer/12345Parameters
| Parameter | Required | Description |
|---|---|---|
|
Yes |
Key secret. |
|
Name of a child database. To access a nested child database, separate the
database names by |
|
|
Yes |
User-defined collection in the database. If a 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 |
|
Yes |
Document ID for the impersonated token’s identity document. The identity
document must be in the |
Impersonate a user-defined role
You typically use this type of scoped key to impersonate a single user-defined role.
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Yes |
Key secret. |
|
Name of a child database. To access a nested child database, separate the
database names by |
|
|
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!