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.

Login

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
Login( identity, param_object )
login( identity, param_object )
Login( identity, param_object )
Login( identity, param_object )
Login( identity, param_object )

Description

The Login function creates an authentication token for the provided identity using the password provided in the param_object. The identity field can be a Reference for the identity document that should be authenticated, or a Set of References (where only the first Reference in the Set is authenticated).

If the identity document does not exist, or the provided password is incorrect, Login returns an error.

The authentication token secret for an authentication token can be used to connect to Fauna and execute queries in the database that has the identity. The permissions granted to the authentication token can be defined using Attribute-based access control (ABAC).

If the identity is not a member of at least one ABAC role, it has no privileges to read or write documents except its own identity document.

Parameters

Parameter Type Definition and Requirements

identity

Reference or Set Reference

The identity (reference to a document). When provided as a Set Reference, the first document reference in the set is used.

param_object

Object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

data

Object

Optional - a document storing metadata about the token to be created.

password

String

The password to authenticate identity with.

ttl

Timestamp

Optional - A timestamp that indicates the time-to-live for a document, which is when the document is removed from the collection and can’t be queried. The document history can continue to be accessed using the Events function, provided the events are in the history retention interval and the document reference is input to the Events function.

Returns

Authentication status Return type Description

Success

Object

An object with the authenticated Reference(s).

Failure

Object

An error is returned.

Examples

client.query(
  q.Login(
    q.Ref(q.Collection('characters'), '181388642114077184'),
    { password: 'abracadabra' },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Tokens(), "268283157930836480"),
  ts: 1592113607250000,
  instance: Ref(Collection("characters"), "181388642114077184"),
  secret: 'fnEDuSIcV7ACAAO5IhwXkAIAMQbrsrZaHs1cUWnligxyD5kUAPE'
}
result = client.query(
  q.login(
    q.ref(q.collection("characters"), "181388642114077184"),
    {"password": "abracadabra"}
  )
)
print(result)
{'ref': Ref(id=269168498780930560, collection=Ref(id=tokens)), 'ts': 1592957934080000, 'instance': Ref(id=181388642114077184, collection=Ref(id=characters, collection=Ref(id=collections))), 'secret': 'fnEDvEdS0pACAAO8R1KZUAIAswCZXMn3gnH_93FC7t_-eRUlqCU'}
result, err := client.Query(
	f.Login(
		f.Ref(f.Collection("characters"), "181388642114077184"),
		f.Obj{"password": "abracadabra"},
	))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[instance:{181388642114077184 0xc00008e3f0 0xc00008e3f0 <nil>} ref:{280481898848846336 0xc00008e240 0xc00008e240 <nil>} secret:fnED5HjNCtACAAPkeMygwAIA1rfQDqKRQAnHrDBoN1a_DgsbVMw ts:1603747233160000]
try
{
    Value result = await client.Query(
        Login(
            Ref(Collection("characters"), "181388642114077184"),
            Obj("password", "abracadabra")
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "280491620815602176", collection = RefV(id = "tokens")),ts: LongV(1603756504750000),instance: RefV(id = "181388642114077184", collection = RefV(id = "characters", collection = RefV(id = "collections"))),secret: StringV(fnED5IGknTACAAPkgaNqIAIAx6peH_1tJ7X82fJ7bcOF6exEWYw))
Login(
  Ref(Collection('characters'), '181388642114077184'),
  { password: 'abracadabra' },
)
{
  ref: Ref(Tokens(), "302044012369412608"),
  ts: 1624310467030000,
  instance: Ref(Collection("characters"), "181388642114077184"),
  secret: 'fnEEMRNtz9ACAAQxE20rQAYAdf5rxVCUGicwNLCuiIB8CjHCqME'
}
Query metrics:

  •    bytesIn:  118

  •   bytesOut:  313

  • computeOps:    1

  •    readOps:    1

  •   writeOps:    1

  •  readBytes:  214

  • writeBytes:  414

  •  queryTime: 56ms

  •    retries:    0

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!