FaunaDB key system
Access to the FaunaDB API uses secrets that correspond to access keys, which authenticate connections as having particular permissions. The access key system applies both to administrator- and server-level connections, as well as to object- and user-level connections.
Keys are defined as documents within the keys collection. Like databases, keys exist within the system-global root database context.
Keys are tied to a specific database and allow access to its contents. If no database is specified, the key grants access to the database in which it was created. The level of access a key provides depends on its role.
You must copy the key’s secret out of the key when it is first created
and store it securely. Only a BCrypt hash of the key is stored on disk.
It is impossible to recover the key’s secret if it is discarded.
| Field name | Value type | Description | ||
|---|---|---|---|---|
|
String |
The key’s role. Either |
||
|
String |
The key’s authentication secret. Only present on creation. |
||
|
String |
The key’s hashed authentication secret. |
||
|
Number |
A priority between 1 and 500, inclusive. Defaults to 1.
|
||
|
Database ref |
The database associated with this key. Optional. |
||
|
Object |
A JSON object. Optional. |
| Once you have key, you can use its secret to authenticate GraphQL queries. |
|
Beginning with FaunaDB 2.11.0, the FaunaDB access control logic has been changed to use attribute-based access control (ABAC) roles, or the key-based permission system, but never both. If a resource is a member of an ABAC role, the ABAC role specifies all privileges for that resource. Otherwise, the key-based permission system determines whether read/write/execute privileges are enabled. For example, when an ABAC role includes a user-defined function as a
member, that function cannot be called unless the ABAC privileges permit
the |
Access keys
Keys belong to one of four built-in roles, either admin, server,
server-readonly, or client, or to one or more used-defined roles.
Admin keys
Keys with the admin role are used for managing databases, keys, and
user-defined roles. An admin key can be used to create and destroy
databases and keys. They should be very well protected.
Admin keys for FaunaDB accounts are managed in the FaunaDB Console.
Server keys
Keys with the server role bypass all permission checks within the
database they’re assigned to. Because they provide unrestricted access,
they should be well protected and only used in trusted or server-side
environments.
Server read-only keys
Keys with the server-readonly role allow read-only access to all data
within the database that they are assigned to. Because they provide
unrestricted read access, they should be well protected and only used in
trusted or server-side environments.
Client keys
Keys with the client role are restricted to actions and resources that
are specifically marked with the public permission. Because their
access is controlled, they are suitable for embedding in untrusted
environments, such as mobile clients.
Typically they are used as part of an application’s user authentication flow, or to access public data, such as an application’s logged-out view.
Was this article helpful?
We're sorry to hear that.
Tell us how we can improve!
documentation@fauna.com
Thank you for your feedback!