Skip to main content

​
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: 
/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.

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

Build docs developers (and LLMs) love

Get started for freeTalk to us