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

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

`Credentials`

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

Credentials( [database] )

credentials( [database] )

Credentials( )
ScopedCredentials( database )

Credentials( [database] )

Credentials( [database] )

Credentials( [database] )

Description

The Credentials function provides the set of existing credential documents in the current database.

Credential documents are used to store the hashed password for a document. They are, most often, created implicitly when a document is created or updated with a top-level credentials object (that documents never store). Credential documents can also be created directly. See Credentials for details.

The Login or Identify functions use the hashed password stored in an identity document’s associated credential document in order to authenticate the identity document.

This function is useful for:

Listing currently existing credentials,
Creating credentials for already-existing documents,
Updating existing credentials (password update).

If you have a reference to a specific credential document, you can add custom fields to the credential document using Update or Replace.

When a credential document is created or updated, a BCrypt hash of the provided password is generated and stored. The original password is never stored on disk.

Parameters

Parameter Type Definition and Requirements

Parameter	Type	Definition and Requirements
`database`	Reference	Optional - A Reference to a child database. If not specified, the current database is used. A Reference to a child database. Optional - A Reference to a child database. If not specified, the current database is used. Optional - A Reference to a child database. If not specified, the current database is used. Optional - A Reference to a child database. If not specified, the current database is used. Optional - A Reference to a child database. If not specified, the current database is used. Optional - A Reference to a child database. If not specified, the current database is used.

database

Reference

Optional - A Reference to a child database. If not specified, the current database is used.

A Reference to a child database.

Optional - A Reference to a child database. If not specified, the current database is used.

Returns

A Set Reference for the set of existing credential documents.

Examples

Create a credential

The following query creates a credential document by specifying a credentials field while creating a document. Notice that the returned document no longer contains the credentials field:

client.query(
  q.Create(
    q.Ref(q.Collection('users'), '3'),
    {
      data: {
        email: 'me@example.com',
      },
      credentials: {
        password: 'abc123',
      },
    }
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  ref: Ref(Collection("users"), "3"),
  ts: 1590014989740000,
  data: { email: 'me@example.com' }
}

result = client.query(
  q.create(
    q.ref(q.collection("users"), "3"),
    {
      "data": {
        "email": "me@example.com",
      },
      "credentials": {
        "password": "abc123"
      }
    }
  )
)
print(result)

{'ref': Ref(id=3, collection=Ref(id=users, collection=Ref(id=collections))), 'ts': 1590015699900000, 'data': {'email': 'me@example.com'}}

result, err := client.Query(
	f.Create(
		f.Ref(f.Collection("users"), "3"),
		f.Obj{
			"data": f.Obj{
				"email": "me@example.com" },
			"credentials": f.Obj{
				"password": "abc123" } }))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:map[email:me@example.com] ref:{3 0xc0000bf710 0xc0000bf710 <nil>} ts:1603747139960000]

try
{
    Value result = await client.Query(
        Create(
            Ref(Collection("users"), "3"),
            Obj(
                "data", Obj(
                    "email", "me@example.com"
                ),
                "credentials", Obj(
                    "password", "abc123"
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(ref: RefV(id = "3", collection = RefV(id = "users", collection = RefV(id = "collections"))),ts: LongV(1603756198370000),data: ObjectV(email: StringV(me@example.com)))

System.out.println(
    client.query(
        Create(
            Ref(Collection("users"), Value(3)),
            Obj(
                "data", Obj(
                    "email", Value("me@example.com")
                ),
                "credentials", Obj(
                    "password", Value("abc123")
                )
            )
        )
    ).get());

{ref: ref(id = "3", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1590015335330000, data: {email: "me@example.com"}}

Create(
  Ref(Collection('users'), '3'),
  {
    data: {
      email: 'me@example.com',
    },
    credentials: {
      password: 'abc123',
    },
  }
)

{
  ref: Ref(Collection("users"), "3"),
  ts: 1624310371040000,
  data: { email: 'me@example.com' }
}

Query metrics:

bytesIn: 164
bytesOut: 176
computeOps: 1
readOps: 0
writeOps: 2
readBytes: 93
writeBytes: 768
queryTime: 57ms
retries: 0

List existing credentials

The following query lists the References for any credentials (up to the pagination limit) in the current database, which includes the credential created in the first example:

client.query(
  q.Map(
    q.Paginate(q.Credentials()),
    q.Lambda('X', q.Get(q.Var('X')))
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  data: [
    {
      ref: Ref(Credentials(), "1"),
      ts: 1601929730630000,
      instance: Ref(Collection("users"), "2"),
      hashed_password: '$2a$05$ChrufpV26Zwrgj/6LA/mlOk6CWWOMrw/hvv2z5mcKH2Ju99JnumXW'
    },
    {
      ref: Ref(Credentials(), "278576109013959168"),
      ts: 1601929730350000,
      hashed_password: '$2a$05$xQOb65pzQNzl2vEjkOwucO7PK/JIHmP65nSP3Kmn7LX.DDV6KnbdO',
      instance: Ref(Collection("users"), "1")
    },
    {
      ref: Ref(Credentials(), "278576109034930688"),
      ts: 1601929730350000,
      hashed_password: '$2a$05$E7jm9xLYIWGN1Dlv88p9SuAETxDq4sW0oxDMNUtkUrhMytxtIjSBi',
      instance: Ref(Collection("characters"), "181388642114077184")
    }
  ]
}

result = client.query(
  q.map_(
    q.lambda_("X", q.get(q.var("X"))),
    q.paginate(q.credentials())
  )
)
print(result)

{'data': [{'ref': Ref(id=1, collection=Ref(id=credentials)), 'ts': 1601929884950000, 'instance': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections))), 'hashed_password': '$2a$05$W5MswKg2Qn/2VIl5aSfgvuBv.w4l.eLki1ybjnxgtIwnPcV206OSK'}, {'ref': Ref(id=278576270823916032, collection=Ref(id=credentials)), 'ts': 1601929884670000, 'hashed_password': '$2a$05$cL35Bbrbf0YThsjwvt2ml.mDBNE1X/rG8Wt2HwNvAzI3cMvS2blR6', 'instance': Ref(id=1, collection=Ref(id=users, collection=Ref(id=collections)))}, {'ref': Ref(id=278576270851179008, collection=Ref(id=credentials)), 'ts': 1601929884670000, 'hashed_password': '$2a$05$iFxL6lFSsrks/1axcvg7meUidqv2VqYEnlT7pOvITPzqXH3SN5Z96', 'instance': Ref(id=181388642114077184, collection=Ref(id=characters, collection=Ref(id=collections)))}]}

result, err := client.Query(
	f.Map(
		f.Paginate(f.Credentials()),
		f.Lambda("X", f.Get(f.Var("X")))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:[map[hashed_password:$2a$05$lo1Uc1sqr/BJ4ieNClNRcOAYEH81ocq1osA/UDlz8wqan7UByNn6K instance:{2 0xc0000b7650 0xc0000b7650 <nil>} ref:{1 0xc0000b74a0 0xc0000b74a0 <nil>} ts:1603747140870000] map[hashed_password:$2a$05$pr/C3URfjEax73piLCNvleCc/qgVvF8to.T4OsH.mS9hFxzVZAp1C instance:{1 0xc00008e2a0 0xc00008e2a0 <nil>} ref:{280481801822011904 0xc0000b7770 0xc0000b7770 <nil>} ts:1603747140630000] map[hashed_password:$2a$05$E0jsZVARQFx38fZtgqWj/.s75qhB.rQ3WblydvH3FEbwTz.FgJcma instance:{181388642114077184 0xc00008e570 0xc00008e570 <nil>} ref:{280481801833546240 0xc00008e3c0 0xc00008e3c0 <nil>} ts:1603747140630000]]]

try
{
    Value result = await client.Query(
        Map(
            Paginate(Credentials()),
            Lambda("X", Get(Var("X")))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(data: Arr(ObjectV(ref: RefV(id = "1", collection = RefV(id = "credentials")),ts: LongV(1603756199360000),instance: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),hashed_password: StringV($2a$05$hJdDKuTFYIkmVSFZcMKD6eGFQ0poVjDwORlLcwmXsGH4qwHY08TWq)), ObjectV(ref: RefV(id = "280491300341416448", collection = RefV(id = "credentials")),ts: LongV(1603756199120000),hashed_password: StringV($2a$05$dkesunx97SZGrTMCe4sgMeOCurm.AlaEys/waE1CfCyzkDtVnkUgq),instance: RefV(id = "1", collection = RefV(id = "users", collection = RefV(id = "collections")))), ObjectV(ref: RefV(id = "280491300342465024", collection = RefV(id = "credentials")),ts: LongV(1603756199120000),hashed_password: StringV($2a$05$V2Z.lSi0VZfJHpTFNmFEx.pCroUf3SlASvvcy.QY5rbIFmnim3gZe),instance: RefV(id = "181388642114077184", collection = RefV(id = "characters", collection = RefV(id = "collections"))))))

System.out.println(
    client.query(
        Map(
            Paginate(Credentials()),
            Lambda("X", Get(Var("X")))
        )
    ).get());

{data: [{ref: ref(id = "1", collection = ref(id = "credentials")), ts: 1601929884950000, instance: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), hashed_password: "$2a$05$W5MswKg2Qn/2VIl5aSfgvuBv.w4l.eLki1ybjnxgtIwnPcV206OSK"}, {ref: ref(id = "278576270823916032", collection = ref(id = "credentials")), ts: 1601929884670000, hashed_password: "$2a$05$cL35Bbrbf0YThsjwvt2ml.mDBNE1X/rG8Wt2HwNvAzI3cMvS2blR6", instance: ref(id = "1", collection = ref(id = "users", collection = ref(id = "collections")))}, {ref: ref(id = "278576270851179008", collection = ref(id = "credentials")), ts: 1601929884670000, hashed_password: "$2a$05$iFxL6lFSsrks/1axcvg7meUidqv2VqYEnlT7pOvITPzqXH3SN5Z96", instance: ref(id = "181388642114077184", collection = ref(id = "characters", collection = ref(id = "collections")))}]}

Map(
  Paginate(Credentials()),
  Lambda('X', Get(Var('X')))
)

{
  data: [
    {
      ref: Ref(Credentials(), "1"),
      ts: 1624310372440000,
      instance: Ref(Collection("users"), "2"),
      hashed_password: '$2a$05$JeoMygtRUkhcYZL0q.v97.OHPnJ7884wKoHiBOHtlJZgSPKosBjpu'
    },
    {
      ref: Ref(Credentials(), "302043912923513344"),
      ts: 1624310372440000,
      hashed_password: '$2a$05$rRJ29kORWsn77mkeNyaWWudl4MFgoJXtTsTyNiK.2YBgw3wTiWCm.',
      instance: Ref(Collection("users"), "1")
    },
    {
      ref: Ref(Credentials(), "302043913015788032"),
      ts: 1624310372440000,
      hashed_password: '$2a$05$bZzDq3xKGsKCkIIeIo2RcedbOL0GLeBUnpdgGY7Xpi73LYdh61f46',
      instance: Ref(Collection("characters"), "181388642114077184")
    }
  ]
}

Query metrics:

bytesIn: 96
bytesOut: 934
computeOps: 1
readOps: 11
writeOps: 0
readBytes: 770
writeBytes: 0
queryTime: 12ms
retries: 0

The following query lists the References for any credentials (up to the pagination limit) in a child database named "child_db":

client.query(
  q.Map(
    q.Paginate(q.Credentials(q.Database('child_db'))),
    q.Lambda('X', q.Get(q.Var('X')))
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{ data: [] }

result = client.query(
  q.map_(
    q.lambda_("X", q.get(q.var("X"))),
    q.paginate(q.credentials(q.database("child_db")))
  )
)
print(result)

{'data': []}

result, err := client.Query(
	f.Map(
		f.Paginate(f.ScopedCredentials(f.Database("child_db"))),
		f.Lambda("X", f.Get(f.Var("X")))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:[]]

try
{
    Value result = await client.Query(
        Map(
            Paginate(Credentials(Database("child_db"))),
            Lambda("X", Get(Var("X")))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(data: Arr())

System.out.println(
    client.query(
        Map(
            Paginate(Credentials(Database("child_db"))),
            Lambda("X", Get(Var("X")))
        )
    ).get());

{data: []}

Map(
  Paginate(Credentials(Database('child_db'))),
  Lambda('X', Get(Var('X')))
)

{ data: [] }

Query metrics:

bytesIn: 115
bytesOut: 24
computeOps: 1
readOps: 8
writeOps: 0
readBytes: 363
writeBytes: 0
queryTime: 24ms
retries: 0

Update a credential (change password)

There are two ways to update a credential.

The following query updates the credential document by updating a document while specifying the credentials field:

client.query(
  q.Update(
    q.Ref(q.Collection('users'), '2'),
    { credentials: { password: 'myNewPassword' } }
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  ref: Ref(Collection("users"), "2"),
  ts: 1601931293490000,
  data: { name: 'Bob User', email: 'bob@site.example.com' }
}

result = client.query(
  q.update(
    q.ref(q.collection("users"), "2"),
    {"credentials": {"password": "myNewPassword"}}
  )
)
print(result)

{'ref': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections))), 'ts': 1601931860380000, 'data': {'name': 'Bob User', 'email': 'bob@site.example.com'}}

result, err := client.Query(
	f.Update(
		f.Ref(f.Collection("users"), "2"),
		f.Obj{"credentials": f.Obj{"password": "myNewPassword"}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:map[email:bob@site.example.com name:Bob User] ref:{2 0xc000156180 0xc000156180 <nil>} ts:1603747143310000]

try
{
    Value result = await client.Query(
        Update(
            Ref(Collection("users"), "2"),
            Obj("credentials", Obj("password", "myNewPassword"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(ref: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),ts: LongV(1603756208270000),data: ObjectV(name: StringV(Bob User),email: StringV(bob@site.example.com)))

System.out.println(
    client.query(
        Update(
            Ref(Collection("users"), "2"),
            Obj("credentials", Obj("password", Value("myNewPassword")))
        )
    ).get());

{ref: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1601931407470000, data: {name: "Bob User", email: "bob@site.example.com"}}

Update(
  Ref(Collection('users'), '2'),
  { credentials: { password: 'myNewPassword' } }
)

{
  ref: Ref(Collection("users"), "2"),
  ts: 1624310378780000,
  data: { name: 'Bob User', email: 'bob@site.example.com' }
}

Query metrics:

bytesIn: 126
bytesOut: 200
computeOps: 1
readOps: 0
writeOps: 2
readBytes: 296
writeBytes: 332
queryTime: 57ms
retries: 0

The following query demonstrates how to update a credential when you have a reference to the credential document itself:

client.query(
  q.Update(
    q.Ref(q.Credentials(), '1'),
    {
      current_password: 'abc123',
      password: 's3kret!',
    }
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  ref: Ref(Credentials(), "266082597906416137"),
  ts: 1590022100100000,
  hashed_password: '$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u',
  instance: Ref(Collection("users"), "2")
}

result = client.query(
  q.update(
    q.ref(q.credentials(), "1"),
    {
      "current_password": "abc123",
      "password": "s3kret!"
    }
  )
)
print(result)

{'ref': Ref(id=266082597906416137, collection=Ref(id=credentials)), 'ts': 1590022100100000, 'hashed_password': '$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u', 'instance': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections)))}

result, err := client.Query(
	f.Update(
		f.Ref(f.Credentials(), "1"),
		f.Obj{
			"current_password": "abc123",
			"password": "s3kret!" }))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[hashed_password:$2a$05$sq9yt4m.hJUSuNz/pcj5pu/OuxQ6p/NCPPT2KMtCaLjw8Gku6zj9q instance:{2 0xc00008f770 0xc00008f770 <nil>} ref:{1 0xc00008f5c0 0xc00008f5c0 <nil>} ts:1603747144970000]

try
{
    Value result = await client.Query(
        Update(
            Ref(Credentials(), "1"),
            Obj(
                "current_password", "abc123",
                "password", "s3kret!"
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(ref: RefV(id = "1", collection = RefV(id = "credentials")),ts: LongV(1603756213160000),instance: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),hashed_password: StringV($2a$05$Mr1ByM81UbU0FjFAVMJtvOcaD6TfnlVks2o8couwCE7WZtQD5P0uC))

System.out.println(
    client.query(
        Update(
            Ref(Credentials(), "1"),
            Obj(
                "current_password", Value("abc123"),
                "password", Value("s3kret!")
            )
        )
    ).get());

{ref: ref(id = "266082597906416137", collection = ref(id = "credentials")), ts: 1590022100100000, hashed_password: "$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u", instance: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections")))}

Update(
  Ref(Credentials(), '1'),
  {
    current_password: 'abc123',
    password: 's3kret!',
  }
)

{
  ref: Ref(Credentials(), "1"),
  ts: 1624310381270000,
  instance: Ref(Collection("users"), "2"),
  hashed_password: '$2a$05$DoPPOepN4tx2arzvikDuKOEguR8EQLE0DULEc9LAiRWvzj3NPFH4i'
}

Query metrics:

bytesIn: 119
bytesOut: 297
computeOps: 1
readOps: 0
writeOps: 1
readBytes: 140
writeBytes: 230
queryTime: 45ms
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!

Credentials

Description

Parameters

Returns

Examples

Related functions

Related topics

`Credentials`