Configuration

Configure SuperTokens Core with config.yaml and environment variables

Configuration

SuperTokens Core is configured using a config.yaml file and environment variables. This page documents all available configuration options.

Configuration file location

The default configuration file is located at:

Docker

/usr/lib/supertokens/config.yaml

You can override the location using the --with-config flag:

./supertokens start --with-config=/path/to/config.yaml

Core configuration

Service settings

port · integer · default: "3567"

The port on which SuperTokens Core runs

port: 3567

host · string · default: "localhost"

The host on which SuperTokens Core runs. Can be localhost, a domain name, 0.0.0.0, or an IP address

host: 0.0.0.0

base_path · string · default: ""

Base path to prepend to all API endpoints

base_path: /auth

With this config, endpoints become /auth/recipe/signup instead of /recipe/signup

max_server_pool_size · integer · default: "10"

Maximum thread pool size for incoming HTTP requests

max_server_pool_size: 20

Logging

info_log_path · string · default: "{installation}/logs/info.log"

Path for INFO level logs. Set to "null" to log to standard output

info_log_path: /var/log/supertokens/info.log

error_log_path · string · default: "{installation}/logs/error.log"

Path for ERROR level logs. Set to "null" to log to standard error

error_log_path: /var/log/supertokens/error.log

log_level · string · default: "INFO"

Logging level. Options: DEBUG, INFO, WARN, ERROR, NONE

log_level: DEBUG

Authentication configuration

Access tokens

access_token_validity · integer · default: "3600"

DIFFERENT_ACROSS_APPS: Time in seconds for access token validity

access_token_validity: 7200  # 2 hours

access_token_dynamic_signing_key_update_interval · integer · default: "168"

DIFFERENT_ACROSS_APPS: Time in hours for signing key rotation

access_token_dynamic_signing_key_update_interval: 24  # Daily rotation

Shorter intervals improve security but increase database queries for key management

Refresh tokens

refresh_token_validity · number · default: "144000"

DIFFERENT_ACROSS_APPS: Time in minutes for refresh token validity

refresh_token_validity: 43200  # 30 days

API keys

api_keys · string · default: "(none)"

DIFFERENT_ACROSS_APPS: Comma-separated API keys for authenticating Backend SDK requests

api_keys: key1-min-20-chars-long,key2-min-20-chars-long

Keys must be at least 20 characters and contain only alphanumeric characters, =, and -

Password authentication

Password hashing

password_hashing_alg · string · default: "BCRYPT"

DIFFERENT_ACROSS_APPS: Password hashing algorithm. Options: BCRYPT, ARGON2

password_hashing_alg: ARGON2

Argon2 is more secure but uses more CPU. Choose based on your threat model and server capacity

BCrypt settings

bcrypt_log_rounds · integer · default: "11"

Number of rounds for BCrypt hashing. Higher values are more secure but slower

bcrypt_log_rounds: 12

Argon2 settings

argon2_iterations · integer · default: "1"

Number of iterations for Argon2 hashing

argon2_iterations: 2

argon2_memory_kb · integer · default: "87795"

Memory usage in KB for Argon2 (default: 85 MB)

argon2_memory_kb: 131072  # 128 MB

argon2_parallelism · integer · default: "2"

Parallelism factor for Argon2

argon2_parallelism: 4

argon2_hashing_pool_size · integer · default: "1"

Number of concurrent Argon2 hash operations allowed

argon2_hashing_pool_size: 2

Password reset

password_reset_token_lifetime · integer · default: "3600000"

DIFFERENT_ACROSS_TENANTS: Password reset token lifetime in milliseconds

password_reset_token_lifetime: 1800000  # 30 minutes

Passwordless authentication

passwordless_code_lifetime · integer · default: "900000"

DIFFERENT_ACROSS_TENANTS: Passwordless code validity in milliseconds

passwordless_code_lifetime: 600000  # 10 minutes

passwordless_max_code_input_attempts · integer · default: "5"

DIFFERENT_ACROSS_TENANTS: Maximum code input attempts before requiring restart

passwordless_max_code_input_attempts: 3

TOTP (MFA)

totp_max_attempts · integer · default: "5"

DIFFERENT_ACROSS_TENANTS: Maximum invalid TOTP attempts before rate limiting

totp_max_attempts: 3

totp_rate_limit_cooldown_sec · integer · default: "900"

DIFFERENT_ACROSS_TENANTS: Rate limit duration in seconds after max attempts reached

totp_rate_limit_cooldown_sec: 1800  # 30 minutes

Email verification

email_verification_token_lifetime · integer · default: "86400000"

DIFFERENT_ACROSS_TENANTS: Email verification token lifetime in milliseconds

email_verification_token_lifetime: 259200000  # 3 days

IP filtering

ip_allow_regex · string · default: "null"

DIFFERENT_ACROSS_TENANTS: Regex pattern for allowed IP addresses

# Allow only localhost
ip_allow_regex: 127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1

ip_deny_regex · string · default: "null"

DIFFERENT_ACROSS_TENANTS: Regex pattern for denied IP addresses

# Deny specific IP range
ip_deny_regex: 192\.168\.1\..*

OAuth configuration

oauth_client_secret_encryption_key · string · default: "null"

Encryption key for OAuth client secrets stored in database

oauth_client_secret_encryption_key: your-32-char-encryption-key-here

Required if you’re using OAuth provider features. Must be exactly 32 characters

oauth_provider_public_service_url · string · default: "null"

URL for OAuth provider public service

oauth_provider_public_service_url: https://oauth.example.com

oauth_provider_admin_service_url · string · default: "null"

URL for OAuth provider admin service

oauth_provider_admin_service_url: https://oauth-admin.example.com

SAML configuration

saml_sp_entity_id · string · default: "https://saml.supertokens.com"

Service provider entity ID for SAML

saml_sp_entity_id: https://saml.myapp.com

saml_claims_validity · integer · default: "300000"

Duration in milliseconds for SAML claims validity

saml_claims_validity: 600000  # 10 minutes

Bulk import

bulk_migration_parallelism · integer · default: "(CPU cores)"

DIFFERENT_ACROSS_APPS: Number of parallel threads for bulk user migration

bulk_migration_parallelism: 4

bulk_migration_batch_size · integer · default: "8000"

DIFFERENT_ACROSS_APPS: Number of users to load per batch during migration

bulk_migration_batch_size: 5000

Monitoring

disable_telemetry · boolean · default: "false"

DIFFERENT_ACROSS_APPS: Disable anonymous telemetry

disable_telemetry: true

Learn more about telemetry: SuperTokens Wiki

otel_collector_connection_uri · string · default: "null"

OpenTelemetry collector URL for distributed tracing

otel_collector_connection_uri: http://localhost:4318

deadlock_logger_enable · boolean · default: "false"

Enable deadlock detection logging

deadlock_logger_enable: true

Environment variables

Most configuration options can be set via environment variables using uppercase with underscores:

# Set port via environment variable
PORT=8080

# Set API keys
API_KEYS=key1-min-20-chars-long,key2-min-20-chars-long

# Set password hashing algorithm
PASSWORD_HASHING_ALG=ARGON2

Environment variables take precedence over config.yaml settings

Configuration scopes

Configuration parameters are marked with scope annotations:

• DIFFERENT_ACROSS_APPS: Can be different for each app in multi-tenancy setup
• DIFFERENT_ACROSS_TENANTS: Can be different for each tenant within an app
• (No annotation): Global configuration, same across all apps and tenants

Example configurations

Development

config.yaml

core_config_version: 0
port: 3567
host: localhost
log_level: DEBUG
disable_telemetry: true

Production

config.yaml

core_config_version: 0

# Service
port: 3567
host: 0.0.0.0
max_server_pool_size: 20

# Security
api_keys: your-production-key-min-20-chars,your-backup-key-min-20-chars

# Tokens
access_token_validity: 3600  # 1 hour
refresh_token_validity: 43200  # 30 days
access_token_dynamic_signing_key_update_interval: 168  # 7 days

# Password hashing
password_hashing_alg: ARGON2
argon2_iterations: 2
argon2_memory_kb: 131072  # 128 MB
argon2_parallelism: 4
argon2_hashing_pool_size: 2

# Logging
log_level: INFO
info_log_path: /var/log/supertokens/info.log
error_log_path: /var/log/supertokens/error.log

# Monitoring
otel_collector_connection_uri: http://localhost:4318

High security

config.yaml

core_config_version: 0

# Strict token lifetimes
access_token_validity: 900  # 15 minutes
refresh_token_validity: 10080  # 7 days
password_reset_token_lifetime: 900000  # 15 minutes

# Strong password hashing
password_hashing_alg: ARGON2
argon2_iterations: 3
argon2_memory_kb: 262144  # 256 MB
argon2_parallelism: 4
bcrypt_log_rounds: 13

# MFA settings
totp_max_attempts: 3
totp_rate_limit_cooldown_sec: 1800  # 30 minutes

# Passwordless security
passwordless_max_code_input_attempts: 3
passwordless_code_lifetime: 300000  # 5 minutes

# IP filtering (adjust regex for your needs)
ip_allow_regex: 10\.0\.\d+\.\d+

Validation

Validate your configuration by starting SuperTokens Core:

./supertokens start --with-config=/path/to/config.yaml

Check the logs for any configuration errors or warnings.

Related documentation

Database setup

Configure your database connection

Docker deployment

Use environment variables with Docker

Self-hosting

Deploy SuperTokens Core to production

Security

Learn about security best practices