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 |
---|
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("<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: key.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 theadmin
role for thechildDB
child database. -
fn…:test/performance:server
creates a scoped key with theserver
role for theperformance
database within thetest
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.
Example
// Scoped key that impersonates an `admin` key for
// the `childDB` child database.
fn...:childDB:admin
Parameters
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/12345
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 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!