Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Authentication

This guide provides a high-level overview of authentication in Fauna.

Secrets

In Fauna, every query is an independently authenticated request to the Query HTTP API endpoint. You authenticate with Fauna using secrets. Secrets are passed to the Fauna HTTP API as bearer tokens.

Each secret is scoped to a specific database or an account’s top-level context. Fauna uses secrets to route requests.

Fauna also uses secrets for authorization. Each secret can have one or more roles. These roles determine the secret’s privileges, which control data access.

You can use the same secret for multiple requests. A secret remains valid until it expires or is deleted.

Secret types

Fauna supports several authentication methods for creating secrets. Different authentication methods create different secret types.

A secret’s type affects how the secret is assigned roles. A secret’s type also determines whether the secret is tied to an identity document. With attribution-based access control (ABAC), you can use an identity document’s attributes to dynamically grant access to data.

The following table outlines each secret type and their differences.

Secret type Primary use Authentication method Role assignment Multiple roles Identity document for ABAC

Secret type	Primary use	Authentication method	Role assignment	Multiple roles	Identity document for ABAC
JSON Web Token (JWT)	End-user authentication	Access providers	Dynamic	Yes	No
Key	Anonymous access. Manage child databases.	None. Typically created by an admin. See Keys.	Static	No	No
Token	End-user authentication	Credentials You can also use `Token.create()` to create tokens without using credentials.	Dynamic	Yes	Yes

JSON Web Token (JWT)

End-user authentication

Access providers

Dynamic

Yes

Key

Anonymous access. Manage child databases.

None. Typically created by an admin.

See Keys.

Static

Token

End-user authentication

Credentials

You can also use Token.create() to create tokens without using credentials.

Dynamic

Yes

An application can use multiple secrets, secret types, and authentication methods at the same time.

Authentication methods

Fauna supports two methods for end-user authentication:

Access providers
Credentials

You can use keys to provide anonymous access to a database.

Access providers

You can configure an external identity provider (IdP) or other JWT issuer, such as Auth0, as an access provider in your Fauna database.

When a user logs in, the IdP issues a JWT. Your application can use the JWT as an authentication secret.

See Access providers

Credentials

A credential associates an end-user password with a Fauna document that represents a user, system, or other identity. This document is called an identity document.

You can use a credential to create tokens that contain an authentication secret. The token’s secret is tied to the identity document. You can use the identity document’s attributes for dynamic ABAC.

See Credentials

Keys

Keys provide anonymous access to a Fauna database. Unlike tokens, keys aren’t associated with an identity.

You can use keys for system processes and applications that don’t require identity-based authentication.

You can also use a key to bootstrap a Fauna-based end-user authentication system. The key can provide the minimum access required for end users to sign up and log in to your application.

You can use scoped keys from a parent database to manage and access child databases.

See Keys

Sessions

Fauna doesn’t use session-based authentication or maintain sessions on the server side.

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!