|
Check out v4 of the Fauna CLI
v4 of the Fauna CLI is now in beta. The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start. |
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() |
|---|
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 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: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 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/789Parameters
| 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 user-defined 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/ownerParameters
| 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. 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
adminrole. -
Use the Dashboard Shell’s authentication drop-down to run a query using a role other than Admin.
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.
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!