Skip to main content


Email configuration

Hasura Auth automatically sends transactional emails to manage the following operations:

  • Sign up
  • Password reset
  • Email change
  • Passwordless with emails

SMTP settings

See the environment variables for additional information about how to connnect to an SMTP server.

Email templates

You can create your own templates to customize the emails that will be sent to the users. You can have a look at the official email templates to understand how they are structured.

With Docker

When using Docker, you can mount your own email templates from the local file system. You can have a look at this docker-compose example to see how to set it up.

Remote email templates

When running Hasura Auth in its own infrastructure, it is possible to mount a volume with custom email-templates directory. However, in some cases, we may want to fetch templates from an external HTTP endpoint. Hence the introduction of a new AUTH_EMAIL_TEMPLATE_FETCH_URL environment variable:


In the above example, on every email creation, the server will use this URL to fetch its templates, depending on the locale, email type and field.

For instance, the template for english verification email body will the fetched in

See the example in the main nhost/nhost repository.

The context variables in email templates have been simplified: the ${link} variable contains the entire redirection url the recipient needs to follow.


Some authentication operations redirects the users to the frontend application:

  • After an OAuth provider completes or fails authentication, the user is redirected to the frontend
  • Every email sent to the user (passwordless with email, password/email change, password reset) contains a link, that redirects the user to the frontend

In order to achieve that, you need to set the AUTH_CLIENT_URL environment variable, for instance:


Email + password authentication

Email checks

You can specify a list of allowed emails or domains with AUTH_ACCESS_CONTROL_ALLOWED_EMAILS and AUTH_ACCESS_CONTROL_ALLOWED_EMAIL_DOMAINS.

As an example, the following environment variables will only allow, and to register to the application:,

In the above example, users with the following emails would be able to register,,, whereas won't.

Similarly, it is possible to provide a list of forbidden emails or domains with AUTH_ACCESS_CONTROL_BLOCKED_EMAILS and AUTH_ACCESS_CONTROL_BLOCKED_EMAIL_DOMAINS.

Password checks

Hasura auth does not accepts passwords with less than three characters. This limit can be changed in changing the AUTH_PASSWORD_MIN_LENGTH environment variable.

It is also possible to only allow passwords that have not been pwned in setting AUTH_PASSWORD_HIBP_ENABLED to true.

Multi-factor authentication

Hasura Auth supports different types of Multi-Factor Authentication (MFA): passwordless with emails (magic links), passwordless with SMS, and Time-based one-time passwords.

Hasura Auth supports email passwordless authentication. It requires SMTP to be configured properly.

Set AUTH_EMAIL_PASSWORDLESS_ENABLED to true to enable passwordless authentication.

Time-based one-time password (TOTP)

It is possible to add a step to authentication with email and password authentication. Once users registered, they can activate MFA TOTP:

  1. Users generate a QR Code, that is then scanned in an authentication app such as Authy or Google Authenticator.
  2. They then send the TOTP code to Hasura Auth. MFA is now activated
  3. Next time they authenticate, Hasura Auth will first expect their email and password, but then, instead of completing authentication, Hasura Auth will expect the TOTP in order to return the refresh and the access tokens.

In order for users to be able to activate MFA TOTP, AUTH_MFA_ENABLED must be set to true.


Hasura Auth stores the avatar URL of users in auth.users.avatar_url. By default, it will look for the Gravatar linked to the email, and store it into this field. It is possible to deactivate the use of Gravatar in setting the AUTH_GRAVATAR_ENABLED environment variable to false.

Extending user schema

Adding columns to the user tables may be tempting. However, all the tables and columns have a specific purpose, and changing the structure of the auth schema will very likely end in breaking the functionning of Hasura Auth. It's, therefore, highly recommended not to modify the database schema for any tables in the auth schema.

Instead, we recommend adding extra user information in the following ways:

  • to store information in the auth.users.metadata column
  • to store information in a separate table located in the public PostgreSQL schema, and to point to through a foreign key.

metadata user field

The auth.users.metadata field is a JSON column, that can be used as an option on registration:

"email": "",
"passord": "12345678",
"options": {
"metadata": {
"first_name": "Bob"

Additional user information in the public schema

As previously explained, the alteration of the auth schema may seriously hamper the functionning of Hasura Auth. The metadata field in the auth.users table may tackle some use cases, but in some other cases, we want to keep a certain level of structure in the way data is structured.

In that case, it is possible to create a dedicated table in the public schema, with a user_id foreign key column that would point to the column. It is then possible to add an Hasura object relationship that would join the two tables together.

Custom Hasura JWT claims

Hasura comes with a powerful authorisation system. Hasura Auth is already configured to add x-hasura-user-id, x-hasura-allowed-roles, and x-hasura-user-isAnonymous to the JSON Web Tokens it generates.

In Hasura Auth, it is possible to define custom claims to add to the JWT, so they can be used by Hasura to determine the permissions of the received GraphQL operation.

Each custom claim is defined by a pair of a key and a value:

  • The key determines the name of the claim, prefixed by x-hasura. For instance, organisation-id will become x-hasura-organisation-id.
  • The value is a representation of the path to look at to determine the value of the claim. For instance will look for the user.profile Hasura relationship, and the profile.organisation Hasura relationship. Array values are transformed into Postgres syntax so Hasura can interpret them. See the official Hasura documentation to understand the session variables format.
AUTH_JWT_CUSTOM_CLAIMS={"organisation-id":"", "project-ids":""}

Will automatically generate and fetch the following GraphQL query:

user(id: "<user-id>") {
profile {
organisation {
contributesTo {
project {

It will then use the same expressions e.g. to evaluate the result with JSONata, and possibly transform arrays into Hasura-readable, PostgreSQL arrays.Finally, it adds the custom claims to the JWT in the namespace:

"": {
"x-hasura-organisation-id": "8bdc4f57-7d64-4146-a663-6bcb05ea2ac1",
"x-hasura-project-ids": "{\"3af1b33f-fd0f-425e-92e2-0db09c8b2e29\",\"979cb94c-d873-4d5b-8ee0-74527428f58f\"}",
"x-hasura-allowed-roles": [ "me", "user" ],
"x-hasura-default-role": "user",
"x-hasura-user-id": "121bbea4-908e-4540-ac5d-52c7f6f93bec",
"x-hasura-user-isAnonymous": "false"
"sub": "f8776768-4bbd-46f8-bae1-3c40da4a89ff",
"iss": "hasura-auth",
"iat": 1643040189,
"exp": 1643041089