GraphQL engine server config examples

The following are a few configuration use cases:

Add an admin secret

To add an admin-secret to Hasura, pass the --admin-secret flag with a secret generated by you.

Run server in this mode using following docker command:

docker run -P -d hasura/graphql-engine:latest graphql-engine \
           --database-url postgres://username:password@host:5432/dbname \
             serve \
             --admin-secret XXXXXXXXXXXXXXXX

Typically, you will also have a webhook for authentication:

docker run -P -d hasura/graphql-engine:latest graphql-engine \
           --database-url postgres://username:password@host:5432/dbname \
             serve \
             --admin-secret XXXXXXXXXXXXXXXX

In addition to flags, the GraphQL Engine also accepts Environment variables.

In the above case, for adding an admin secret you will use the HASURA_GRAPHQL_ADMIN_SECRET and for the webhook, you will use the HASURA_GRAPHQL_AUTH_HOOK environment variables.

Using CLI commands with admin secret

When you start the GraphQL Engine with an admin secret key, CLI commands will also need this admin secret to contact APIs. It can be set in config.yaml or as an environment variable or as a flag to the command. For example, let’s look at the case of the console command:

In the my-project/config.yaml file, set a new key admin_secret:

# config.yaml

The console can now contact the GraphQL APIs with the specified admin secret.


If you’re setting admin_secret in config.yaml please make sure you do not check this file into a public repository.

An alternate and safe way is to pass the admin secret value to the command as an environment variable:

hasura console

# OR in a single line
HASURA_GRAPHQL_ADMIN_SECRET=xxxxx hasura console

You can also set the admin secret using a flag to the command:

hasura console --admin-secret=XXXXXXXXXXXX


The order of precedence for admin secret and endpoint is as follows:

CLI flag > Environment variable > Config file

Configure CORS

By default, all CORS requests to Hasura GraphQL engine are allowed. To run with more restrictive CORS settings, use the --cors-domain flag or the HASURA_GRAPHQL_CORS_DOMAIN ENV variable. The default value is *, which means CORS headers are sent for all domains.

Scheme + host with optional wildcard + optional port has to be mentioned.


# Accepts from , etc.

# Accepts from ,,
# http://app.localhost, http://api.localhost, http://localhost:3000,
# etc.
HASURA_GRAPHQL_CORS_DOMAIN="https://*, http://*.localhost, http://localhost:3000,"

# Accepts from all domain

# Accepts only from


Top-level domains are not considered as part of wildcard domains. You have to add them separately. E.g - https://* doesn’t include

You can tell Hasura to disable handling CORS entirely via the --disable-cors flag. Hasura will not respond with CORS headers. You can use this option if you’re already handling CORS on a reverse proxy etc.