login()

Log in to Fauna.

Signature

login(password: String): Token | NullToken

login(password: String, ttl Time): Token | NullToken

Description

The login() method authenticates an identity in Fauna by providing the password for a Credential document. Attempts to login with an incorrect password result in an error. Call update() to set a new password.

This method creates a token when it authenticates an identity.

Required privileges

To call login() in a query, your access token must have a role with the create privilege for the built-in Token collection. For example:

role myRole {
  ...
  privileges Token {
    create
  }
}

The built-in admin and server roles have this privilege.

User-defined functions (UDFs) can be assigned an optional role. If assigned, this role supersedes the access token’s privileges. If a UDF includes login(), the UDF’s role must have the create privilege for the Token collection.

Multiple tokens

If you call this method multiple times, it creates multiple tokens. This is because an identity may have multiple tokens that can access multiple devices simultaneously.

Parameters

Parameter Type Required Description

password

String

Yes

Credential document password.

ttl

Time

Timestamp indicating a document lifespan. When the ttl is reached, Fauna removes it. If ttl isn’t set, its default value is null, which causes the document to persist indefinitely or until deleted.

Return value

Type Description

Token

Login token, which includes the secret key.

Examples

The following simplified sequence creates a user and associates credentials with the user, which can then be used to log in.

  1. Create a user in the example Person collection:

    Person.create({
  name: "mario",
  email: "mario@hello.com",
  password: "sekret"
})
    {
  id: "373273910203908129",
  coll: Person,
  ts: Time("2023-08-17T02:49:51.180Z"),
  name: "mario",
  email: "mario@hello.com",
  password: "sekret"
}

  2. Create a user credential, including the password:

    Credentials.create({
  document: Person.byId("373273910203908129"),
  password: "sekret"
})
    {
  id: "373273931423940641",
  coll: Credential,
  ts: Time("2023-08-17T02:50:11.420Z"),
  document: Person.byId("373273910203908129")
}

  3. Log in with a password:

    Credentials.byId("373273931423940641")!.login("sekret")
    {
  id: "373274451635077153",
  coll: Token,
  ts: Time("2023-08-17T02:58:27.540Z"),
  document: Person.byId("373273910203908129"),
  secret: "fnEFLiMi1XAAIQUh3mNk4AAhMPnjoGQZDiyoEG89cM40a9_sDrw"
}

You can also combine the procedure into a single expression:

Credential.byDocument(Person.byId("373273910203908129"))!.login("sekret")

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!