credential.login()

Learn: Credentials

Create a token for a provided credential and its password.

Signature

login(secret: String) => Token

login(secret: String, ttl: Time) => Token

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 credential.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 Token system collection. For example:

role manager {
  ...
  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

secret

String

true

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

Token, which includes the token’s secret.

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 Customer collection:

    Customer.create({
  name: "John Doe",
  email: "john.doe@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "12345",
    country: "United States"
  }
})
    {
  id: "999",
  coll: Customer,
  ts: Time("2099-07-31T13:16:15.040Z"),
  cart: null,
  orders: "hdW...",
  name: "John Doe",
  email: "john.doe@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "12345",
    country: "United States"
  }
}

  2. Create a user credential, including the password:

    Credential.create({
  document: Customer.byId("999"),
  password: "sekret"
})
    {
  id: "412654692679549440",
  coll: Credential,
  ts: Time("2099-06-25T13:27:23.170Z"),
  document: Customer("999")
}

  3. Log in with a password:

    let document = Customer.byId("999")
Credential.byDocument(document)?.login("sekret")
    {
  id: "412654692933304832",
  coll: Token,
  ts: Time("2099-07-31T13:17:46.900Z"),
  document: Customer("111"),
  secret: "fn..."
}
\