Log in and log out

This tutorial shows you how to log in as associated users with a token, and how to log out by deleting the token.

The examples in this tutorial use the Fauna Dashboard and Fauna’s demo data.

Overview

In Fauna, you manage users and other identities, such as servers or processes, as documents in one or more collections. For example, Fauna’s demo data includes the Customer and Manager collection. Each document in these collections represents an end user for a client app. Each collection can be assigned to one or more security roles with overlapping privileges.

To associate an identity document with a password, you create a credential, which is stored as a document in the built-in Credential collection. A document can have only one associated credential.

You can use a credential and its password to generate an access token, which you can use as a Fauna API key to access data on a user’s behalf. The access token inherits its privileges from the document’s roles.

You can optionally specify a ttl (time-to-live) to set the token’s expiration. If no ttl is provided, the token persists until deleted.

Log in

In the Demo database, add a new Customer document. Then create a credential for the customer and use it to generate a Fauna access token.

  1. In the Dashboard Shell for the Demo database, select the built-in Admin role.

    Admin role in the Dashboard Shell}

    You must have the create and read privileges for the Credential and Token collections to create an access token from a credential. The Admin role has these privileges.

  2. Create a new document in the Customer collection:

    Customer.createData({
  firstName: "Jane",
  lastName: "Doe",
  email: "jane.doe@example.com"
})

  3. Use Credential.create() to create a credential for the customer and their password

    let customer = Customer.byName("Jane", "Doe")
  .first()

Credential.create({
  document: customer,
  password: "sekret"
})

  4. Use login() to create a token using the customer’s credential and password.

    let customer = Customer.byName("Jane", "Doe").first()
let credential = Credentials.byDocument(customer)

credential?.login("sekret")

    The response includes the access token in the secret property. A client app can use this token to access Fauna data on behalf of the customer.

    {
  id: "371287435110252578",
  coll: Token,
  ts: Time("2023-07-26T04:35:40.910Z"),
  document: Customer("371264255805095970"),
  secret: "..."
}

    Save the token. You’ll use it later to log out.

Log out

To log out, delete the token. The Query.token() method gives you the Token document for the query’s authentication token.

  1. In the Fauna Shell, select Secret and enter your token secret.

    Subsequent queries you enter use this secret.

  2. Verify that you’re using the correct token:

    Query.token()
    {
  id: "371287435110252578",
  coll: Token,
  ts: Time("2023-07-26T04:35:40.910Z"),
  document: Customer.byId("371264255805095970")
}

    Because you are using the token secret, Fauna knows your identity and allows you to make queries on your identity documents.

  3. To log out, delete the token:

    Query.token()!.delete()
    Token.byId("371287435110252578") /* permission denied */

  4. Verify that the query fails because the secret is no longer valid:

    Product.all()
    unauthorized

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!