FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, review the migration guide. Contact support@fauna.com with any questions.

Tokens

Fauna tokens provide identity-based access to a database.

An identity typically represents a "user", but could also be used to identify any service, system, or process that needs to run queries with specific privileges. Any document within Fauna can be used as an identity.

When an identity stored in Fauna is successfully authenticated, using the Login function, a new token is created. Tokens can also be created directly when identity-based access is required, but authentication is unnecessary or handling outside of Fauna.

When a token is created, you must copy the token’s secret out of the query result when it is first created, and store it securely. It is impossible to recover the token’s secret if it is discarded or lost, because the token only stores the BCrypt hash of the secret.

A token’s secret is then included as a bearer token in Fauna queries:

Identity-based authentication and access control with Fauna tokens

How Fauna performs identity-based authentication

  • The client sends a query to Fauna, and the request includes the secret for a Token as an HTTP bearer token header.

  • If the secret exists, Fauna looks up the associated Token document within the database associated with the secret. If not, the response is Unauthorized.

  • If the Token exists and has not expired (due to ttl), Fauna looks up the associated identity document. If not, the response is Unauthorized.

  • If the identity document exists and has not expired (due to ttl), Fauna applies ABAC roles to determine whether the identity document is permitted to execute the query. If not, the response is Unauthorized.

  • If the identity document has permission, the query is executed and the response is returned.

A token’s secret can be used in multiple queries until its token becomes invalid or is deleted.

By itself, a token does not grant any privileges to the identity. The privileges available to an identity are defined by Attributed-based access control (ABAC)).

During the execution of a query, the CurrentIdentity function can be used to access the stored identity for the active token.

Multiple tokens can exist for a particular identity. This feature could be used to provide identity-based access on multiple devices at once.

A token is deleted by calling the Logout function, and all tokens for an identity stored in Fauna can be deleted at once. Once a token is deleted, its associated secret is immediately invalidated.

Tokens are defined as documents within the system tokens collection. Like databases, tokens exist within the system-global root database context. Tokens are tied to a specific database.

A token’s secret is a password equivalent. Guard secrets with the same care and attention that you use for passwords.

Definition

{
  ref: Ref(Tokens(), "266165140418724353"),
  ts: 1590093708340000,
  instance: Ref(Collection("users"), "123456"),
  hashed_secret: '$2a$05$Zsg5cWmMxfj4cbeeaiOVAe1eTrxxgAtQSO53m6Lw3vjp10vcefm2i'
}
Field name Value type Description

ref

Reference

The reference for this token.

ts

Long

The timestamp, with microsecond resolution, associated with the creation of the token.

instance

Reference

The reference to the identity document associated with the token.

secret

String

The token’s authentication secret. Not stored: only present on creation of a token, not recoverable if lost or discarded.

hashed_secret

String

The token’s hashed authentication secret.

data

Object

Optional - User-defined metadata for the token.

Operations on tokens

  • Create a token with the Login function. A successful login requires a reference to a document that has a credentials object that defines the document’s password, and passing the same password to Login.

  • Creation of a token can also be done directly, without a credentials field on the to-be-authenticated document and without providing a password, by running the following query:

    Create(Tokens(), { instance: <document ref> })

    Where <document ref> is a Reference to the document that should be authenticated.

    A token is typically created in a query that uses a key for authentication. Direct token creation while using a client key requires a password. For all other key types, the password is optional.

  • To logout a user, call the Logout function while using a token. The token in use is deleted. Logout accepts a boolean value that, when true, deletes all tokens associated with the authenticated document for the current session (that is using a token). Once a token is deleted, its associated secret immediately becomes invalid.

  • Tokens can be deleted by using the Delete function. Deleting a token immediately invalidates its associated secret.

  • Modify a token’s optional user-defined metadata (the data field) by using the Update function.

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!